Upgrade an existing project

Availability

Available in hosted CLI 0.6.14, which pins MCP 0.2.14. Native connector 0.1.6 includes CLI 0.6.14/MCP 0.2.14 and can perform the recognized upgrade after account connection through its existing installer. Use the command below for an explicit offline preview or local upgrade. Custom files remain a local review case; earlier archives remain unchanged.

Upgrading the CLI does not automatically change existing project settings. The command updates an existing Claude Code or Codex installation after recognizing Maglev’s original files. Custom configurations still need manual review.

Preview, apply, verify

Install the current CLI, then preview the selected project:

npm install -g https://trymaglev.com/downloads/maglev-cli-0.6.14.tgz
maglev agent upgrade --target claude --directory /path/to/project --dry-run --json
maglev agent upgrade --target claude --directory /path/to/project --json

Use --target codex for Codex. Choose one explicit project directory. No login, API key or network request is needed. This command only examines and updates the existing Maglev connection configuration and its project skill; it does not scan engineering files or contact suppliers.

The dry run reports the old and new package pins, file paths and SHA-256 hashes. It creates no profile, lock, backup or project file. A successful apply returns status: "upgraded", an operation ID and a private backup directory. It does not print the configuration or its other tools’ credentials.

Reload or restart your agent. Ask it to check get_identity, then inspect its available tools. The offline upgrade returns hostConnectionVerified: false: changing a file does not prove that the host loaded it or that the account has access. This release changes no API permissions and does not sign in again.

What it can update

Target	Connection file	Skill file
Claude Code	.mcp.json	.claude/skills/maglev-manufacturing/SKILL.md
Codex	.codex/config.toml	.agents/skills/maglev-manufacturing/SKILL.md

Both files must already exist as regular files owned by the current user. The command recognizes released Maglev skill bytes and connection templates from CLI 0.6.0 onward where retained release evidence exists. A current bundled template is recognized directly. Earlier installations and unreviewed development builds require manual review.

Only the exact Maglev package URL is replaced inside the connection file. Other servers, comments, formatting and values remain byte-for-byte unchanged. The configured API origin and project transfer root are preserved. A skill is replaced only when it matches a recognized original. Unrelated AGENTS.md, CLAUDE.md, engineering files and Maglev credential records are not read or changed. Settings for other tools inside the connection file are read and backed up as part of preserving that file.

The command stops for custom skill instructions, extra Maglev arguments or environment variables, an unrecognized package, a different project root, duplicate JSON keys, malformed configuration, symlinks, hard links, changed ownership or oversized files. It does not guess how to merge those changes. A configuration is limited to 256 KiB and a skill to 128 KiB.

Hermes and OpenClaw use different host settings and require a manual version review in this release. maglev agent install is still for a new skill; maglev setup still preserves a conflicting existing installation.

Backups and interruption recovery

Before replacing either project file, the command stores both original and intended files under the private Maglev profile’s upgrades/OPERATION_ID/ directory. The default profile is ~/.maglev; an explicitly configured MAGLEV_CONFIG_DIR is respected. On Unix, backup directories are mode 0700 and backup files are 0600. These backups can contain other MCP tools’ settings or secrets: keep them private and out of Git, chat and support attachments.

Two project files cannot be replaced atomically together. If the process stops after replacing one, rerun the same command with the same CLI version, target, project and profile. After a hard crash, wait at least one minute for the process lease to expire. The command verifies the saved backup and each current file, skips files already at their intended bytes and completes the remaining replacement. It does not repeat login or execute either MCP server.

A user edit or permission change after interruption stops recovery. So does a missing, modified or redirected backup, an unrelated lock or a partial/unrecognized temporary file. Keep the private backups, compare the affected files locally and resolve the specific conflict. Do not delete the entire configuration or profile. If you intentionally migrate to a newer CLI during an unfinished upgrade, finish or manually reconcile the earlier operation first.

Completed backups remain available for an intentional manual rollback. The tool does not silently roll back a working configuration after a later human edit. Locks coordinate Maglev’s own writers; close other configuration editors while upgrading.

Results and errors

Value	Meaning
upgrade_available	Dry-run plan found recognized files that differ from the installed CLI’s templates
already_current	Both project files already match; they were not rewritten
upgraded	Both files were checked at their intended final bytes and the recovery record completed
recoveryPending: true	Dry run found an incomplete saved operation
upgrade_custom_configuration / upgrade_custom_skill	The original is not an exact recognized template; review it locally
upgrade_project_changed	A project file’s bytes or permissions changed after preparation
upgrade_invalid_recovery / upgrade_unsafe_path	Saved evidence or file paths cannot be trusted for automatic replacement
recovery_locked / upgrade_configuration_busy	Another process or an unverifiable lock prevents an update
upgrade_temporary_conflict	A temporary file differs from the complete intended contents

An error can occur after one replacement. Consult the saved operation and backups; an error does not mean that no local change occurred. These statuses describe local installation only, not supplier authority, engineering approval or production readiness.