Skip to main content
The Momentic CLI runs tests on your laptop and in CI. Use the same command in both places, and let its exit code gate the merge. Your tests stay as plain-English YAML files in your repository.

​
Basic usage

Omit a test argument to run every web test. Pass a file, directory, or test-name substring to run a smaller set. Use the mobile CLI for mobile tests.

​
Authenticate

momentic run needs an API key. Run the login command to save a key in ~/.momentic/auth.json, set MOMENTIC_API_KEY, or pass --api-key. Without a key, the CLI stops with: “API key is required. Run npx momentic login or set MOMENTIC_API_KEY.”

​
Select which tests run

Pass positional arguments as file paths, directories, or test-name substrings. Use --labels to filter by label. Use --include and --exclude with regex patterns that match part of a test path. Run npx momentic list with the same arguments to preview the match. Add --ai-select to select tests from the git diff. See AI test selection for details.

​
Choose an environment and base URL

The --env <name> flag takes priority. If the flag is absent, Momentic uses defaultEnv in the test. See environments for the configuration. For web tests, the base URL comes from --url-override, then the test’s own url, then BASE_URL from the selected environment. Mobile tests have no base URL. They use a channel and a tag instead. See hosted test environments.

​
Pass variables and secrets

Variable values resolve in this order: CLI flags, shell values when inheritFromShell: true, then envVariables or envFile in momentic.config.yaml. Keep secrets in a .env file or CI secret storage. See Environment variables for the configuration. Read a shell value in a test with {{ env.API_TOKEN }}.

​
Run in parallel and shard

Use --parallel 4 or --parallel auto to run tests concurrently. The default is 1, and the config key is parallel. Use --shard-index and --shard-count to split a suite across machines. See Performance for tuning guidance.

​
Boot your app first

Use --start to boot your app before the test. Use --wait-on to wait for a resource before the test starts. --wait-on-timeout defaults to 60 seconds.

​
Machine-readable output

Pass --reporter more than once to combine reporters. list is the default live terminal reporter. steps writes append-only lines for CI logs. File reporters write to --reporter-dir, which defaults to ./reports: json, junit, allure, allure-json, playwright-json, and buildkite-json. Run artifacts go to --output-dir, which defaults to ./test-results and contains the live progress.json file. Add --upload-results to send the run to the dashboard. See Results and reporting.

​
Exit codes

The command reports one of these exit codes. Quarantined tests run by default, but their statuses do not affect the exit code. Use --ignore-quarantine to apply them, --only-quarantined to run only them, or --skip-quarantined to skip them. See automatic maintenance and the quarantine command. With classification enabled, --classify-override-exit-code makes failures routed to heal or warn exit with 0.

​
Reproduce a CI failure locally

Run the same command locally that you use in CI. To replay a snapshot in full isolation, use --from-snapshot. The zip provides the modules, environment, and step caches. Snapshot mode cannot combine with test paths or selection flags. See snapshot replay.

​
Run in CI

The -y and --yes options are implied when CI is set. See the GitHub Actions guide and custom CI setups for copy-paste workflows. The custom setup guide covers other providers, which are also listed in the sidebar.

​
Watching for changes

During development, use the local editor for a tighter feedback loop.
See the full momentic run reference and momentic-mobile run reference for every flag.