# How to Upgrade Existing Projects Using agents-cli scaffold upgrade

> Safely upgrade your existing projects with agents-cli scaffold upgrade. This command merges template updates with your code, preserving customizations.

- Repository: [Google/agents-cli](https://github.com/google/agents-cli)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/agents-cli-manifest.yaml) using `find_project_root` and `find_project_config` (lines 23-25 in [`upgrade.py`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/merge.py) lines 71-84 and [`upgrade.py`](https://github.com/google/agents-cli/blob/main/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:

```bash

# 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:

```python
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`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/commands/upgrade.py)**: Main implementation of the upgrade command logic
- **[`src/google/agents/cli/scaffold/utils/merge.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/utils/merge.py)**: Core three-way merge engine and template generation
- **[`src/google/agents/cli/scaffold/utils/version.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/utils/version.py)**: Version retrieval and comparison utilities
- **[`src/google/agents/cli/scaffold/cmd_scaffold_group.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/cmd_scaffold_group.py)**: CLI command registration and group structure
- **[`src/google/agents/cli/_project.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/_project.py)**: Project manifest parsing and metadata extraction
- **[`src/google/agents/cli/_tools.py`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/agents-cli-manifest.yaml) upon completion
- All merge logic resides in [`src/google/agents/cli/scaffold/commands/upgrade.py`](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/commands/upgrade.py) with utilities in [`src/google/agents/cli/scaffold/utils/merge.py`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/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`](https://github.com/google/agents-cli/blob/main/agents-cli-manifest.yaml) file (handled in [`src/google/agents/cli/_project.py`](https://github.com/google/agents-cli/blob/main/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.