GitHub Copilot modernization agent CLI commands

The GitHub Copilot modernization agent provides both interactive and non-interactive modes for application modernization.

Command modes

Interactive mode

Launch the interactive Text User Interface (TUI) for guided modernization:

modernize

The interactive mode provides:

• Menu-driven navigation through the modernization workflow.
• Flexible source selection: current folder, manual input (local paths or Git URLs), or repository config files.
• Visual plan and progress indicators.
• Guided prompts for configuration options, including assessment domains and parameters.
• Multi-repository selection interface.

Non-interactive mode

Execute specific commands directly for automation and scripting:

modernize <command> [options]

Use non-interactive mode when:

• Integrating with CI/CD pipelines.
• Automating batch operations.
• Scripting modernization workflows.
• Running in headless environments.

Global options

All commands support these global options:

Commands

assess

Runs an assessment and generates a comprehensive analysis report.

Syntax

modernize assess [options]

Options

Examples

Basic assessment of current directory:

modernize assess

Assess with custom output location:

modernize assess --output-path ./reports/assessment

Assess and update GitHub issue with results:

modernize assess --issue-url https://github.com/org/repo/issues/123

Assess specific project directory:

modernize assess --source /path/to/project

Assess multiple repositories by using a config file:

modernize assess --source .github/modernize/repos.json

Assess multiple repositories by specifying sources directly:

modernize assess --source https://github.com/org/repo1 --source https://github.com/org/repo2

Assess and output reports in markdown format:

modernize assess --format markdown

Output

The assessment generates:

• Report files: Detailed analysis in JSON, MD, and HTML formats.
• Summary: Key findings and recommendations.
• Issue updates (if you provide --issue-url): GitHub issue comment with summary.

plan create

Creates a modernization plan based on a natural language prompt describing your modernization goals.

Syntax

modernize plan create <prompt> [options]

Arguments

Options

Examples

Generate a migration plan:

modernize plan create "migrate from oracle to azure postgresql"

Generate an upgrade plan with custom name:

modernize plan create "upgrade to spring boot 3" --plan-name spring-boot-upgrade

Generate a deployment plan:

modernize plan create "deploy the app to azure container apps" --plan-name deploy-to-aca

Full options example:

modernize plan create "upgrade to .NET 8" \
    --source /path/to/project \
    --plan-name dotnet8-upgrade \
    --language dotnet \
    --issue-url https://github.com/org/repo/issues/456

Prompt examples

Framework upgrades:

• upgrade to spring boot 3
• upgrade to .NET 10
• upgrade to JDK 21
• migrate from spring boot 2 to spring boot 3

Database migrations:

• migrate from oracle to azure postgresql
• migrate from SQL Server to azure cosmos db
• switch from MySQL to azure database for mysql

Cloud migrations:

• migrate from on-premises to azure
• containerize and deploy to azure container apps
• migrate from rabbitmq to azure service bus

Deployment:

• deploy to azure app service
• deploy to azure kubernetes service
• set up CI/CD pipeline for azure

Output

The command generates:

• Plan file (.github/modernize/{plan-name}/plan.md): Detailed modernization strategy including:

  • Context and goals
  • Approach and methodology
  • Clarifications

• Task list (.github/modernize/{plan-name}/tasks.json): Structured breakdown of executable tasks with:

  • Task descriptions
  • Skills to use
  • Success criteria

plan execute

Executes a modernization plan created by modernize plan create.

Syntax

modernize plan execute [prompt] [options]

Arguments

Options

Examples

Execute the most recent plan interactively:

modernize plan execute

Execute a specific plan:

modernize plan execute --plan-name spring-boot-upgrade

Execute with extra instructions:

modernize plan execute "skip the test" --plan-name spring-boot-upgrade

Execute in headless mode for CI/CD:

modernize plan execute --plan-name spring-boot-upgrade --no-tty

Execution behavior

During execution, the agent:

1. Loads the plan: Reads the plan and task list from .github/modernization/{plan-name}/

2. Executes tasks: Processes each task in the task list sequentially:

   • Applies code transformations.
   • Validates builds after changes.
   • Scans for CVEs.
   • Commits changes with descriptive messages.

3. Generates summary: Provides a report of all changes and results.

Output

• Commit history: Detailed commits for each task executed.
• Summary report: Overview of changes, successes, and any problems encountered.
• Build validation: Confirmation that the application builds successfully.
• CVE report: Security vulnerabilities identified and addressed.

upgrade

Runs an end-to-end upgrade workflow - plan, and execute - in a single command.

Syntax

modernize upgrade [prompt] [options]

Arguments

Options

Examples

Run upgrade on the current directory:

modernize upgrade "Java 17"

modernize upgrade ".NET 10"

Run upgrade on a specific project:

modernize upgrade "Java 17" --source /path/to/project

Run upgrade by using the Cloud Coding Agent:

modernize upgrade "Java 17" --delegate cloud

Upgrade multiple repositories by using a config file:

modernize upgrade "Java 21" --source .github/modernize/repos.json

Upgrade multiple repositories by specifying sources directly:

modernize upgrade "Java 21" --source https://github.com/org/repo1 --source https://github.com/org/repo2

help

Provides help and information commands.

Syntax

modernize help [command]

Commands

Examples

List available models:

modernize help models

Configure the CLI

By using the modernization agent, you can customize application behavior through JSON files and environment variables.

Environment variables

Set environment variables to override all other configuration scopes:

Example:

export MODERNIZE_LOG_LEVEL=debug
export MODERNIZE_MODEL=claude-sonnet-4.6
modernize assess

User configuration

Store user-specific preferences in ~/.modernize/config.json or repository-wide settings in .github/modernize/config.json.

{
  "model": "claude-sonnet-4.6",
  "log_level": "info",
  "trusted_folders": [
    "/path/to/trusted/project",
  ]
}

The trusted_folders property specifies the folders that are trusted to use LLM in interactive mode.

Multi-repository configuration

You can provide multiple sources to the CLI in several ways:

• Repository config file: Create a .github/modernize/repos.json file that lists all repositories, then pass it with --source.
• Multiple --source flags: Specify local paths or Git URLs directly on the command line.
• Interactive mode: Select sources through the TUI (current folder, manual input, or repository config).

Repository config file

Create a .github/modernize/repos.json file to define your repository list. The config supports two formats:

Simple format (array of repositories):

[
  {
    "name": "PhotoAlbum-Java",
    "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git"
  },
  {
    "name": "PhotoAlbum",
    "url": "https://github.com/Azure-Samples/PhotoAlbum.git"
  }
]

Full format (with branch and local paths):

{
  "repos": [
    {
      "name": "PhotoAlbum-Java",
      "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git",
      "branch": "main"
    },
    {
      "name": "local-project",
      "path": "/absolute/path/to/project"
    }
  ]
}

Each repo entry supports the following fields:

Full format with app grouping (optional, for organized reporting):

You can add an apps[] section to group repositories into logical applications. When apps are defined, the aggregated report organizes results by application and supports report distribution.

{
  "repos": [
    {
      "name": "PhotoAlbum-Java",
      "url": "https://github.com/Azure-Samples/PhotoAlbum-Java.git",
      "branch": "main"
    },
    {
      "name": "PhotoAlbum",
      "url": "https://github.com/Azure-Samples/PhotoAlbum.git"
    }
  ],
  "apps": [
    {
      "identifier": "photo-app",
      "description": "Photo management application",
      "repos": ["PhotoAlbum-Java"],
      "output": {
        "type": "local",
        "path": "/path/to/reports/photo-app"
      }
    }
  ]
}

Each app entry supports:

The output field supports the following distribution types:

Then use --source to pass the config file path:

Assess all repositories locally:

modernize assess --source .github/modernize/repos.json

Assess all repositories by using the Cloud Coding Agent:

modernize assess --source .github/modernize/repos.json --delegate cloud

Upgrade all repositories by using the Cloud Coding Agent:

modernize upgrade --source .github/modernize/repos.json --delegate cloud

Multiple sources on the command line

You can also specify multiple sources directly:

modernize assess --source https://github.com/org/repo1 --source https://github.com/org/repo2

modernize upgrade "Java 21" --source ./project-a --source ./project-b

Next steps

• Batch assessment: Assess multiple applications
• Batch upgrade: Upgrade multiple applications
• Create custom skills for your organization
• Return to overview