GitHub Copilot modernization CLI

What is GitHub Copilot modernization CLI?

GitHub Copilot modernization provides AI-powered capabilities to help users modernize Java and .NET applications easily and confidently.

Organizations modernizing multiple applications need consistency, repeatability, and the ability to define standards that apply across every dev team and repository. The GitHub Copilot Modernization Agent is built for these requirements.

Delivered through the Modernize CLI, the modernization agent enables agentic, end-to-end application modernization through intelligent workflow orchestration. It provides architects and app owners with a platform to define modernization standards once - via customizable, reusable skills - and apply them consistently across multiple applications and repositories. It offers a unified CLI and TUI experience for hands-on modernization of individual applications.

Learn More

For detailed documentation, tutorials, and additional resources, visit the GitHub Copilot Modernization Agent documentation.

🖥️ Supported Platforms

• Windows (x64, ARM64)
• Linux (x64, ARM64)
• macOS (Apple Silicon, Intel)

🔧 Prerequisites

Minimum requirements:

• Git
• GitHub CLI (gh) v2.45.0 or later
• GitHub Copilot subscription with Free, Pro, Pro+, Business and Enterprise plans, See Copilot plans.

Installation

Linux / macOS

Option 1 — Homebrew:

brew tap microsoft/modernize https://github.com/microsoft/modernize-cli
brew install modernize

Option 2 — Shell script:

curl -fsSL https://raw.githubusercontent.com/microsoft/modernize-cli/main/scripts/install.sh | sh

The script automatically downloads the latest release, install the modernize bundle to ~/.local/share/modernize, place the modernize command in ~/.local/bin, and add the command directory to your PATH.

After installation, reload your shell profile to apply the PATH update:

source ~/.bashrc   # or source ~/.zshrc for Zsh

Note

For Linux users: Requires glibc 2.27+ (Ubuntu 18.04+, Debian 10+, Fedora 29+, Azure Linux 2.0+).

Windows

Option 1 — Winget:

winget install GitHub.Copilot.modernization.agent

For silent installation (no prompts):

winget install GitHub.Copilot.modernization.agent --silent

Option 2 — PowerShell one-liner:

iex (irm https://raw.githubusercontent.com/microsoft/modernize-cli/main/scripts/install.ps1)

Option 3 — MSI installer:

Download and run the latest MSI from the Releases page.

All three options place the modernize command in %LOCALAPPDATA%\Programs\modernize and add it to your PATH automatically.

Note

After installation, open a new terminal for the modernize command to be available on your PATH.

---

Use the interactive mode

The easiest way to get started is using the interactive mode. First, authenticate with the GitHub CLI:

gh auth login

Then, run the modernization agent:

modernize

You'll be guided through the end-to-end modernization experience via the main menu:

○ How would you like to modernize your Java app?

  > 1. Assess application
       Analyze the project and identify modernization opportunities
    2. Create modernization plan
       Generate a structured plan to guide the agent
    3. Execute modernization plan
       Run the tasks defined in the modernization plan

Commands

Global options

All commands support these global options:

Option	Description
--help, -h	Display help information
--no-tty	Disable interactive prompts (headless mode)

assess

Runs assessment and generates a comprehensive analysis report.

Syntax

modernize assess [options]

Options

Option	Description	Default
--source <path>	Path to source project (relative or absolute local path)	. (current directory)
--output-path <path>	Custom output path for assessment results	.github/modernize/assessment/
--issue-url <url>	GitHub issue URL to update with assessment summary	None
--multi-repo	Enable multi-repo assess. Scans first-level subdirectories for multiple repositories	Disabled
--model <model>	LLM model to use	claude-sonnet-4.6
--delegate <delegate>	Execution mode: local (this machine) or cloud (Cloud Coding Agent)	local
--wait	Wait for delegated tasks to complete and generate results (only valid with --delegate cloud)	Disabled
--force	Force restart delegation, ignoring ongoing tasks (only valid with --delegate cloud)	Disabled

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 repos in current directory:

modernize assess --multi-repo

plan create

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

Syntax

modernize plan create <prompt> [options]

Arguments

Argument	Description
<prompt>	Natural language description of modernization goals (required)

Options

Option	Description	Default
--source <path>	Path to the application source code	Current directory
--plan-name <name>	Name for the modernization plan	modernization-plan
--language <lang>	Programming language (java or dotnet)	Auto-detected
--overwrite	Overwrite an existing plan with the same name	Disabled
--model <model>	LLM model to use	claude-sonnet-4.6

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

plan execute

Executes a modernization plan created by modernize plan create.

Syntax

modernize plan execute [prompt] [options]

Arguments

Argument	Description
[prompt]	Optional natural language instructions for execution (e.g., "skip tests")

Options

Option	Description	Default
--source <path>	Path to the application source code	Current directory
--plan-name <name>	Name of the plan to execute	modernization-plan
--language <lang>	Programming language (java or dotnet)	Auto-detected
--model <model>	LLM model to use	claude-sonnet-4.6
--delegate <delegate>	Execution mode: local (this machine) or cloud (Cloud Coding Agent)	local
--force	Force execution even when a CCA job is in progress	Disabled

Examples

Execute the most recent plan interactively:

modernize plan execute

Execute a specific plan:

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

Execute with additional 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

upgrade

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

Syntax

modernize upgrade [<prompt>] [options]

Arguments

Argument	Description
[<prompt>]	Target version (e.g., Java 17, Spring Boot 3.2, .NET 10). Defaults to latest LTS.

Options

Option	Description	Default
--source <source>	Path to source project (relative or absolute local path)	. (current directory)
--delegate <delegate>	Execution mode: local (this machine) or cloud (Cloud Coding Agent)	local
--model <model>	LLM model to use	claude-sonnet-4.6

Examples

Run upgrade on 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 using the Cloud Coding Agent:

modernize upgrade "Java 17" --delegate cloud

help

Provides help and information commands.

Syntax

modernize help [command]

Commands

Command	Description
models	List available LLM models and their multipliers

Examples

List available models:

modernize help models

Environment variables

Variable	Description	Default
MODERNIZE_COLLECT_TELEMETRY	Enable/disable telemetry collection	true
MODERNIZE_LOG_LEVEL	Logging level (debug, info, warn, error)	info

Example:

export MODERNIZE_COLLECT_TELEMETRY=false
modernize assess

Feedback

We're thrilled to have you join us on the early journey of the modernization agent. Your feedback is invaluable—please share your thoughts with us!

Disclaimer

Unless otherwise permitted under applicable license(s), users may not decompile, modify, repackage, or redistribute any assets, prompts, or internal tools provided as part of this product without prior written consent from Microsoft.