Skip to main content
The simplified format makes Momentic YAML easier to review and maintain: no volatile step IDs on disk, shorter command aliases, relative module references, and JSON Schema support in modern editors.
The migration rewrites Momentic test and module files. Back up your repository first, start from a clean Git state, and make sure there are no untracked changes before running it.
Web (momentic) and mobile (momentic-mobile) are separate CLIs with separate migrations. Each command only rewrites files belonging to its own CLI and sets fileFormat: v2 on the selected project’s momentic.config.yaml. If your repo has both web and mobile Momentic projects, run both migrations; one will not touch the other’s files.

​
Migrate with a coding agent

Paste this prompt into your coding agent. It checks the working tree, runs the migration, reinstalls the skills, and reviews the diff with you.

​
Before you start

Pick a migration window when teammates are not actively changing Momentic tests. Everyone should move to the simplified format at roughly the same time. If one branch keeps editing legacy YAML while another branch lands the rewrite, later merges can be noisy. Before running the migration:
Commit, stash, or otherwise back up any local changes before continuing. For an extra local backup, create a branch before the migration:
Check Node.js before running the CLI:
The current web and mobile CLIs require Node.js 22.12.0 or later in the 22.x line, or 24.0.0 or later. Update unsupported versions, including Node.js 20 and 23, in your local runtime and CI before upgrading.

​
1. Update Momentic

Invoke the full upgrade through momentic@latest / momentic-mobile@latest so the project config and YAML rewrites are produced by the new CLI’s serializers, not the version currently pinned in your package.json. Running the bare npx momentic upgrade on an older pinned version installs the new CLI but completes the rest of the upgrade with the old one, which means you would need a second invocation to see the new behavior take effect. Read the CLI version in the project’s package.json and lockfile. Also check explicit versions in CI install commands and MCP editor configs. Run only the version command for the CLI already installed in that project:
If your MCP server is pinned in an editor config, update that command too. The MCP server must run a version that understands simplified format files before agents can create, preview, or edit them.

​
2. Run the migration

Authenticate with momentic login (or momentic-mobile login for mobile), or provide MOMENTIC_API_KEY for the workspace. The migration writes identity snapshots to retain existing step caches. Upgrade previews also authenticate, although they do not write snapshots. You have two entry points, depending on how much of the project you want to change:
  • momentic@latest upgrade / momentic-mobile@latest upgrade: the full upgrade. Installs the latest CLI into your project, applies the latest recommended project-config defaults (ai.agentConfig agent versions, ai.useMemory, ai.failureRecovery), sets fileFormat: v2, and rewrites included legacy test and module files when the project’s format is still legacy. It can replace older agent pins and explicitly enables memory and failure recovery, including when those settings were disabled. Review the dry-run diff before applying it.
  • momentic migrate simplified-format / momentic-mobile migrate simplified-format: file migration only. Rewrites legacy test and module files to the simplified format and flips fileFormat: v2 on the project config, but leaves your CLI version and ai.* defaults alone. Use this when you want a tight, isolated diff with no config-default changes mixed in. Runs against the CLI version already installed in your project; if it is older than the published momentic@latest the command will warn you and point at npx momentic@latest upgrade so you can install the newest serializers.
Both paths share the same serializer and use the project’s include and exclude configuration to discover files. Explicit migration skips files that already use the simplified format. If the config already says fileFormat: v2 but legacy files remain, use migrate simplified-format; upgrade skips the file conversion for projects already configured for v2. The migration can fail after writing some files. The full upgrade also installs the CLI before converting YAML, so package and lockfile changes can remain after a failure. Restore the changes from that attempt, fix the reported problem, and rerun. Some legacy constructs, such as section steps or conditionals with multiple branches or else steps, cannot be serialized directly. Refactor those tests while preserving their behavior before retrying.

​
Preview with --dry-run

Both upgrade commands accept --dry-run to preview config changes and file counts without installing a new project dependency, rewriting project files, or pushing snapshots. This is a conversion preview; it does not execute tests or prove that their behavior is equivalent:
The output lists how many tests and modules would be migrated, how many already use the simplified format, and which ai.agentConfig entries would be updated. Conversion counts are shown for legacy-format projects. If the config already says v2, the preview skips file discovery and does not report leftover legacy files.

​
Web

From the web project root, run one of:
A typical web test in the simplified format should start with fileType: momentic/test/v2; a module should start with fileType: momentic/module/v2.

​
Mobile

From the mobile project root, run one of:
A typical mobile test in the simplified format should start with fileType: momentic/mobile-test/v2; a mobile module should start with fileType: momentic/mobile-module/v2. If you maintain both a web and a mobile project, run the command in each project root. Neither CLI touches the other’s files, so a single-platform run will silently leave the other platform’s tests in legacy YAML.

​
Web and mobile sharing one config

The first upgrade sets the shared fileFormat to v2. The second CLI’s upgrade then skips file conversion, even if that platform’s files are still legacy. After upgrading both packages, explicitly migrate the remaining platform. For example, when upgrading web first:
If mobile was upgraded first, run npx momentic migrate simplified-format after the web upgrade instead. For a file-only migration, run both CLIs’ migrate simplified-format commands; those commands inspect the files even when the shared config already says v2.

​
What to expect

The migration preserves existing step caches across the conversion. Duration depends on the number of files and the snapshot writes. Review the renamed fields, command options, and relative file references in the diff. A few changes to check: Do not convert durations by hand across the suite: some legacy fields already use milliseconds. Let the CLI perform the conversion, then compare the timing of representative tests. Validate the files and runs below before committing. Include the config, rewritten YAML, updated skills, and any package manifest and lockfile changes in the same migration commit. Align explicit CI and MCP pins with the installed CLI so teammates and CI can load the new format. If your repo already uses the simplified format and the agent config is current, the project config and YAML do not need rewriting. The upgrade command can still update the installed CLI package.

​
3. Reinstall Momentic skills

The Momentic skills teach coding agents and the MCP server how to author and edit simplified format files, including which MCP tools to reach for when making small edits to the readable YAML. Reinstall them from your project root after the migration so every editor that reads them picks up the latest guidance:
Use npx momentic-mobile skills --yes for mobile projects. The command detects .claude/, .cursor/, .agents/, .opencode/, and .github/ directories and rewrites the installed skill files in place. Run it once after the migration, then restart your editor so it loads the new skill content.

​
4. Enable editor validation

Momentic publishes static JSON Schemas for simplified format tests and modules. Add them to your editor to get autocomplete and inline validation as you write. The schemas work for web, mobile, and mixed repos. See IDE lint for VS Code, Cursor, Windsurf, and Zed config. The onboarding wizard (npx @momentic/wizard@latest) configures this automatically for the editors it detects.

​
5. Use lint for agent edits

Editor schemas catch shape errors early. Momentic also runs simplified format lint automatically before starting the local app and before executing tests, so the local app and test runs already block invalid YAML. Use the lint command when a coding agent or direct YAML edit changes Momentic test files and you want validation without starting the app or running tests. It checks schema validity, local file references, and entity conflicts. Web:
Mobile:
Run the matching command once after the migration, then use it as a check for agent-authored changes. To check one file during review:

​
Verify migrated behavior

If you upgraded the web CLI and run local browsers, reinstall the browser builds used by your tests with momentic install-browsers. The upgrade does not download them. A file-only migration does not change browser builds. Use list to confirm the expected suite is discovered, then run an actual test path from that output. Replace the example paths and retain the environment, browser, and app build options from your previous run:
Compare the starting state, setup and cleanup, assertions, retries, and recovery activity with the legacy run. Then run the affected suite in CI using the committed lockfile and the same selection. Confirm that the expected tests actually ran, including parameterized cases. Review disabled or skipped tests, quarantine, recovered passes, and failure classifications. Exit code 0 alone does not prove equivalent behavior. Lint validates file structure and references; it cannot prove behavioral equivalence. For rollback, restore the migration’s YAML, config, and package changes together and reinstall dependencies from the restored lockfile. For a committed migration, revert the migration commit. Reverting only fileFormat leaves the project’s files and CLI version inconsistent.

​
6. Author simplified format files

After migration, restart your editor so it launches the updated MCP command when you do need browser-backed authoring. MCP is still the supported way to create, preview, and execute steps against a live browser. For lightweight changes, simplified format files are also fine to edit directly. The readable YAML format, static schemas, and editor completions make small updates easier:
  • Prompt coding agents to directly edit *.test.yaml and *.module.yaml for changes that do not need a browser.
  • Hand-author tests with YAML tab completions and schema suggestions in your editor.
  • Reference local files from steps. JavaScript steps can point at local JS files, and those JS files can reference other local files with relative paths.
See File format for the top-level YAML structure, Steps for step syntax, and MCP for MCP setup. For a spec-driven process that uses Momentic tests as product specs, see Spec-driven development on the Skills page.