Upgrade and migrate

upgrade

Update agnostic-ai using the method you installed it with. update is an alias.

agnostic-ai upgrade
agnostic-ai upgrade --check              # show install details without updating
agnostic-ai upgrade --version v0.81.0    # install a specific release

Automatic upgrade offers

When you run a command in a terminal, a stable release build checks for updates at most once a day. Release checks have a five-second network limit. The offer is two lines, the version change and a link to the release page, then the prompt:

Update available: 0.83.0 -> 0.85.0
Release guidance: https://github.com/Chemaclass/agnostic-ai/releases/tag/v0.85.0
Update now? [Y/n]

Press Enter or type y to accept. Type n to continue your original command; the offer will not repeat that day.

In a project, accepting it:

1. Installs the new release and checks that the new executable has the expected version.
2. Sets the project's required version (requires) to that exact release and updates the editor schema link. This replaces a minimum or range too, including an existing value in agnostic-ai.local.yaml.
3. Previews and applies the built-in changes to old spec files.
4. Runs sync, then sync --check.

Outside a project, it updates the tool only. After accepting, rerun your original command with the updated tool. Read the release page for steps you must do yourself.

If a config file, .agnostic-ai, or .agnostic-ai/local links to another project or the global specs folder, the offer is skipped and names that location. Links within the project are supported.

For project-local npm or pnpm installs, the offer prints the package manager's update command. For npx, it prints a command with the new version. Run that command yourself. Automatic npm updates are limited to confirmed global installs; that check has a two-second limit.

If installation or version checking fails, project changes do not start. If a later step fails, the tool stops and prints how to continue. Changes already completed stay in place.

Set AGNOSTIC_AI_NO_UPDATE_CHECK=1 to disable these checks. Offline checks stay silent. Checks also skip CI, redirected input or output, JSON output, quiet mode, global commands, checks, previews, hooks, completion, editor services, and development builds. You can still run upgrade yourself.

Upgrade options

After updating through a package manager, run its installed CLI from the project root:

pnpm exec agnostic-ai upgrade --requires

--requires replaces a minimum, range, or older version with the exact installed release. It updates the base config and any existing local requires value, including null. Comments and other settings stay. If sync fails, the version changes stay: fix the reported problem and run sync again.

This option needs a stable release build and also supports agnostic.config.yaml. It cannot combine with --check, --version, or --run. It leaves the global config, package-manager files, and dependency files to their own update commands.

The config must have one root setting per line and a single-line requires value. If it uses {...} at the root, YAML << merges, or a requires value shared through &/* or spread across several lines, rewrite those parts first.

The Scoop, WinGet, and node_modules paths match in any letter case. upgrade also reports other copies on PATH that would run instead of the one it found.

migrate

Update spec files that use old field names or formats. Sync writes the same files afterward, so sync --check stays clean. The one exception is a literal MCP credential, which becomes a ${NAME} reference. Old forms keep working, so you never have to run it before a sync. doctor and upgrade --requires name the migrations that apply.

agnostic-ai migrate --list      # which migrations apply here
agnostic-ai migrate --dry-run   # preview the rewrites
agnostic-ai migrate             # apply them
agnostic-ai migrate --global    # rewrite the global specs

See credential previews for shared reference and display rules.

• A migration rewrites only what it can replace without changing its meaning. Anything else stays as written, and the output says why.
• When secrets-mcp-literals turns a credential into a reference, its output names each variable to set, never the value.
• A symlinked spec keeps its symlink; the file it points to gets the rewrite.
• It never rewrites a pack or a spec linked into one. The output names the pack.
• Migrations stay within the project and its local specs folder. With --global, they stay within the global specs folder and its local folder. A linked local folder is included too.
• A migration that cannot plan, for example on a spec that does not parse, prints cannot plan with the reason. The others still run, and migrate exits 1.
• doctor names a migration only when it rewrites something or a skip needs your action, such as a spec that sets both the old and the new form. --dry-run and --list show every skip.