How to Upgrade Existing Projects Using agents-cli scaffold upgrade

The agents-cli scaffold upgrade command performs a three-way merge between the original scaffolding template, the current template, and your existing project files to safely modernize your codebase without overwriting customizations.

The google/agents-cli repository provides a robust upgrade mechanism for projects created with earlier versions of the CLI. The agents-cli scaffold upgrade command automates the tedious process of reconciling template updates with your custom business logic, ensuring you always have the latest framework improvements while maintaining your project's unique modifications.

How the Three-Way Merge Works

The upgrade process in src/google/agents/cli/scaffold/commands/upgrade.py implements a sophisticated three-way merge strategy that compares three distinct states:

1. The original template (captured by acli_version in agents-cli-manifest.yaml)
2. The current template (shipped with your installed CLI version)
3. Your live project files (current customizations)

Step 1: Project Discovery and Version Validation

First, the command locates your project root by searching for agents-cli-manifest.yaml using find_project_root and find_project_config (lines 23-25 in upgrade.py). It then reads the acli_version field and compares it against the currently installed CLI version via get_current_version (lines 24-36).

Step 2: Legacy Migration

Before merging, the tool handles backward compatibility. It calls migrate_legacy_python_config, migrate_legacy_evalsets, and warn_legacy_eval_config (lines 12-14, 66-68) to convert deprecated configuration formats to the new layout, ensuring smooth transitions from older CLI versions.

Step 3: Baseline Template Generation

The system requires uvx (verified by _ensure_uvx_available on lines 39-45) to fetch the exact historic CLI version. It then generates a temporary snapshot of how your project originally looked using either _run_vendored_create or _run_pinned_create (invoked via run_create_command in merge.py lines 71-84 and upgrade.py lines 70-82).

Step 4: Merge Execution

The run_three_way_merge function (lines 70-82) executes the actual merge, automatically applying non-conflicting changes from the new template while preserving your custom edits. Conflicts are either surfaced for manual resolution or handled according to your chosen flags.

Step 5: Version Metadata Update

Upon successful completion, the inline _update_version function (lines 61-64) updates the acli_version field in your manifest to match the new CLI version, establishing the new baseline for future upgrades.

Command-Line Options and Execution Modes

The upgrade command supports several execution modes via flags defined in the CLI:

Flag	Behavior
--dry-run / --dryrun	Preview changes without modifying files
--auto-approve / -y	Automatically apply all non-conflicting changes
--interactive / -i	Prompt for resolution of each conflict
--debug	Enable verbose logging for troubleshooting

Running the Upgrade Command

Basic usage from the command line:

# Run from project directory or specify path

agents-cli scaffold upgrade path/to/project

# Preview changes without applying

agents-cli scaffold upgrade . --dry-run

# Auto-approve non-conflicting updates

agents-cli scaffold upgrade . --auto-approve

# Interactive conflict resolution

agents-cli scaffold upgrade . --interactive

# Debug mode for troubleshooting

agents-cli scaffold upgrade . --debug

Programmatic Usage

You can also invoke the upgrade logic directly from Python scripts:

from google.agents.cli.scaffold.commands.upgrade import upgrade
from pathlib import Path

upgrade(
    project_path=Path("/my/agent/project"),
    dry_run=False,
    auto_approve=True,
    interactive=False,
    debug=False,
)

Key Source Files

• src/google/agents/cli/scaffold/commands/upgrade.py: Main implementation of the upgrade command logic
• src/google/agents/cli/scaffold/utils/merge.py: Core three-way merge engine and template generation
• src/google/agents/cli/scaffold/utils/version.py: Version retrieval and comparison utilities
• src/google/agents/cli/scaffold/cmd_scaffold_group.py: CLI command registration and group structure
• src/google/agents/cli/_project.py: Project manifest parsing and metadata extraction
• src/google/agents/cli/_tools.py: Tool availability checking (e.g., uvx requirement)

Summary

• The agents-cli scaffold upgrade command performs a three-way merge between original templates, current templates, and your custom code
• It automatically handles legacy migrations and requires uvx to fetch historical CLI versions
• Use --dry-run to preview changes and --auto-approve to apply safe updates automatically
• The upgrade process updates the acli_version field in agents-cli-manifest.yaml upon completion
• All merge logic resides in src/google/agents/cli/scaffold/commands/upgrade.py with utilities in src/google/agents/cli/scaffold/utils/merge.py

Frequently Asked Questions

What happens if I don't have uvx installed?

The command will fail with a clear error message. The _ensure_uvx_available function in upgrade.py (lines 39-45) explicitly checks for uvx availability because it is required to fetch the exact historical version of the CLI used when your project was first scaffolded. Install uvx via your package manager before running the upgrade.

Will the upgrade command overwrite my custom code?

No, the three-way merge logic specifically preserves your customizations. It only applies changes from the new template to files you haven't modified. Conflicts between your changes and template updates are either left for manual resolution (default) or handled according to your --auto-approve or --interactive flags.

Can I see what changes will be made before applying them?

Yes, use the --dry-run flag. This executes the entire merge logic without writing any changes to disk, allowing you to review exactly which files would be modified, added, or deleted before committing to the upgrade.

How does the command know which version of the template to use as the baseline?

The command reads the acli_version field from your project's agents-cli-manifest.yaml file (handled in src/google/agents/cli/_project.py). This stored version tells the upgrade tool exactly which historical CLI version to fetch via uvx to recreate the original template state for comparison.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}