Skip to main content
momentic upgrade updates the installed CLI and the project configuration. It:
  • installs the latest matching CLI release,
  • sets fileFormat: v2,
  • refreshes recommended agent versions and enables ai.useMemory and ai.failureRecovery, and
  • converts included legacy test and module files when the project is still configured for the legacy format.
An agent pin is retained if it matches the current recommendation or extends that recommendation with a sub-version (for example, v5.0 when the recommendation is v5). Older pins can be replaced, and disabled memory or failure recovery settings are enabled. Review the dry-run config diff. The command skips files already using the simplified format. When the file format and recommended AI settings are current, it leaves project files unchanged; the CLI package installation can still update the installed version. If the config already has fileFormat: v2 but legacy files remain, use the explicit migration command to convert them. For only the YAML rewrite without any other config changes, use momentic migrate simplified-format instead.
Always invoke momentic@latest on first run. The CLI version bump writes your new version to package.json, but the rest of the upgrade still runs in the currently-installed process, so an old pinned CLI would migrate files with its old serializer until the next invocation. The real upgrade installs the CLI before conversion. A failure can leave package/lockfile changes and partial YAML rewrites. Follow the migration and validation procedure before retrying or committing the result.

​
Options

​
string
Path to the Momentic configuration file. When omitted, Momentic searches the current directory and its parents for momentic.config.yaml or a workspace configuration. Use this flag to select a project when discovery finds more than one.
​
string
Momentic API key. Defaults to MOMENTIC_API_KEY, then the key saved by login in ~/.momentic/auth.json.
​
boolean
Skip confirmation prompts. Start from a backed-up, clean working tree.
​
boolean
Preview the upgrade without writing any files or pushing snapshots. Prints the same diff-style summary you would see during a real run so you can review changes before applying them. Requires authentication through login or MOMENTIC_API_KEY; does not run tests.

​
Examples

Run the full upgrade in place:
Preview what would change: