select
Analyze the current git diff and return the tests most likely to catch a
regression. This command prints the selection without executing tests. To select
and run tests in one command, use
momentic run --ai-select.
string
Base branch, tag, or commit to diff against
HEAD. Momentic detects the pull
request base in supported CI providers and otherwise falls back to
origin/HEAD.number
Soft cap on the number of tests selected. AI test selection can exceed it to
cover distinct changed behavior.
string
Additional selection guidance appended to the built-in AI test selection
instructions. Repeatable; values are appended in command-line order. Omitting
the flag leaves the standard selection prompt unchanged.
boolean
Print the structured selection result to stdout without the streaming UI.
boolean
Skip the local import index and select using the diff and app graph.
boolean
Skip app graph search and select using local code evidence only.
classify
Classify the result of a test run. The agent inspects step results, screenshots,
and error details and returns a category with reasoning.
For CI, prefer enabling classification in
momentic.config.yaml so momentic run classifies failures in-flow and saves the verdict automatically, with no
separate ai classify step. See Turn on in-flow
classification. Use this command to
re-classify past runs, batch-classify a run group or commit, or ask follow-up
questions with --interactive.--run-id (one or more run IDs or URLs), --run-group-id (a run
group ID or URL), or --git-commit. Multiple failed runs are classified in
parallel with an aggregated summary.
Options
string
Classify one or more runs by ID or full run URL (e.g.
https://app.momentic.ai/runs/<runId>). Pass multiple space-separated values
to classify several runs in one invocation. Passing more than one run cannot
be combined with --interactive.string
Classify every failed run in an uploaded run group, by run group ID or full
run group URL (e.g.
https://app.momentic.ai/run-groups/<runGroupId>).string
Classify every failed run recorded at the given git commit SHA, across all run
groups.
boolean
When targeting a run group or commit, skip runs that already have a saved
classification. Useful for resuming a partially-completed batch.
number
Number of runs to classify in parallel when targeting a run group or commit.
Defaults to
4. The effective value is shown in the run banner.string
Output format for the classification. Defaults to
text. Use json to print
only the structured payload to stdout.boolean
Suppress the agent’s streamed reasoning. Redundant when
--output-format json
is set.boolean
Persist the classification into the run’s metadata. For local runs, this
updates the local run zip; for uploaded runs, it updates the dashboard run.
When targeting a run group or commit, each run is saved as it finishes. New
result-classification cache entries are only written when
--save is set.boolean
Ignore prior result-classification cache entries and do not write new cache
entries. By default, classification can reuse prior classifications from the
result-classification cache. If
--save is also set, successful
classifications can write new cache entries for future runs.boolean
After classifying, stay in an interactive terminal chat with the
classification agent. Useful for asking follow-up questions about the run (why
a step failed, what the screenshots show, related runs, etc.) without
re-running classification. Single-run only and requires a TTY; cannot be
combined with
--run-group-id, --git-commit, or --output-format json.
Type exit (or Ctrl-C) to leave; Ctrl-C during a response cancels just that
turn.Output
By default, the classification is printed as plain text:--output-format json to emit a machine-readable payload instead:
json payload is
an array, one entry per run; entries that failed to classify carry an error
field instead of a classification:
--skip-classified to retry
only the runs that did not complete.
Categories
enum
No failures, all attempts passed.
enum
The test is out of date because the application’s flow or UI has changed.
Updating the test to match the new behavior would permanently fix the failure.
enum
Something clearly went wrong in the application that shouldn’t have, such as
an unexpected error message appearing or expected content failing to render.
enum
The test can be permanently updated to prevent the failure while still
validating its original intent, and a specific authorship change can be
recommended. Timeouts, slow page loads, and any failure whose recommended fix
is to wait longer or increase a timeout do not belong here. Those are
INFRA,
even when the test could technically be edited to wait longer.enum
Missing test data or files necessary to run the test, where the fix requires
user action outside of the test itself (e.g. a missing file for a file upload
step, or missing/incorrect credentials).
enum
A failure unrelated to the application or application code that was caused by
an infrastructure outage, long load times, or some other outside factor.
enum
An issue with Momentic’s own execution (e.g. incorrect cache entries,
unexpected locator redirects, obvious AI hallucinations).
enum
The failure doesn’t fit any of the other categories.
triage
Runs the triage agent over a local results archive from
momentic run or an uploaded run group.
The agent investigates failures, groups them by shared fixes when possible,
attempts to update tests in place, and writes the outcome back to the run group.
momentic ai heal is an alias with the same behavior and flags.
When processing a local results archive, the command automatically uploads the
updated archive after processing so the dashboard and connected reporting
receive the final results and validation signal. Pass --no-upload to keep the
archive local. This automatic upload also runs after --dry-run triage.
For a copy-paste CI setup and the different integration paths, see Auto-heal
failing tests in CI.
[results] archive, --run-group-id,
--run-id, or --git-commit. When multiple runs are passed via --run-id,
they are triaged together in a single bucketing pass.
Arguments
string
Path to a local results archive directory written by
momentic run. The
directory must contain a run group metadata file. Omit when using
--run-group-id, --run-id, or --git-commit.Target and output
string
Triage an already uploaded run group by ID or full run group URL (e.g.
https://app.momentic.ai/run-groups/<runGroupId>) instead of a local results
archive. Automatic upload does not apply because there is no local archive.string
Triage one or more uploaded runs by ID or full run URL. Pass multiple
space-separated values to triage several runs together in one bucketing pass.
The run-group risk-summary write-back is skipped for this scope.
string
Triage every failed run recorded at the given git commit SHA, flat across all
run groups. The run-group risk-summary write-back is skipped for this scope.
boolean
Group failed tests and generate a validation signal without attempting or
applying repairs. A local results archive is still uploaded by default. Add
--no-upload to skip the archive upload.string
How an accepted repair is delivered. Accepts
pull-request,
draft-pull-request, direct-commit-except-main, patch (print a git patch
to stdout), or nothing (leave the changes on disk). Overrides the On
successful heal Triage setting
for this run.string
What happens to tests the agent cannot fix. Accepts
warn, fail, or
quarantine. Overrides the On failed heal Triage
setting for this run.boolean
Suppress progress output and print the triage result as JSON.
boolean
After triaging, stay in an interactive terminal chat with the triage agent so
you can ask follow-up questions. This cannot be combined with
--json.boolean
Do not automatically upload the local results archive after processing. The
generated validation signal may still update connected pull request reporting.
This flag has no effect when using
--run-group-id.Common flags
string
Path to the Momentic configuration file. Defaults to
momentic.config.yaml in
the current directory.string
When using workspaces, load the project whose name
matches the filter.
string
Number of healing attempts to run in parallel. Each attempt opens its own
browser session. Defaults to
1.number
Abort when the number of healable failed runs exceeds this threshold. Must be
a positive integer.
array
Exclude tests whose name or project-relative file path matches any of the
provided regex patterns from the triage queue. Provide multiple patterns
separated by spaces. A pattern only needs to match part of the name or path
for that test to be skipped.
Emits high fidelity diagnostics for the triage agent to enable Momentic to
help you debug your agent’s failure. Do not default to turning this on.
Environment
string
Environment to run replays in. Overrides any environment configured on the
test itself.
string
Override the base URL of the test or environment during the replay.
array
Custom headers to include in the replay. Specify multiple headers separated by
spaces.
string
CSV file containing input data for the replay. Each row is used as input for a
separate run.
Browser
string
Override the browser used for replays. Accepts
chromium, chrome, or
chrome-for-testing.boolean
Launch healing browser sessions headfully by default. Useful for visually
watching the agent work. Env:
MOMENTIC_HEADFUL_BROWSER.number
Device pixel ratio for the healing browser. Set to
2 on macOS Retina or
other HiDPI displays.Caching
boolean
Always save updated step caches after a successful heal, even on the main and
other protected Git branches.
boolean
Disable step caches entirely. Steps run without cached data and no caches are
saved.
boolean
Ignore previously cached heal solutions during triage so failures are healed
from scratch. Newly successful heals are still saved; step caches are
unaffected.
Quarantine
boolean
Only attempt to heal quarantined tests. Failed runs outside quarantine are
ignored.
Recovery
boolean
Skip tests that passed through in-run failure recovery instead of assessing
whether they need a permanent repair. Failed tests are still triaged.
Setup
string
Command to run before the replay begins. Useful for booting a local dev
server.
string
HTTP proxy used when polling
--wait-on. Provide the full URL including
protocol, optional credentials, host, and port.number
Timeout (in seconds) for
--wait-on. Defaults to 60. Triage fails if the
resource is not reachable in time.CI
number
Maximum total triage time, in minutes. When reached, in-flight healing
attempts stop and the current results are flushed.
boolean
Suppress the agent’s streamed reasoning.
boolean
Skip all confirmation prompts. Enabled by default when
CI is set.Exit codes
triage is the final status for a run group: a non-zero exit code means
something still needs your attention.
0- every failure was either successfully healed or, when On failed heal iswarn, logged as a warning. A successful heal does not fail the run on its own; the delivered fix (e.g. a pull request) is yours to review and merge.1- a test could not be healed and On failed heal isfailorquarantine, or delivering an accepted repair failed (e.g. opening the pull request errored), or the triage run itself errored out.
explore
For the conceptual overview, see the Explore agent guide.
The explorer agent identifies user-facing changes (including backend changes
that surface to the user), reports the user journeys they touch, and by default
opens a live browser session to author or edit Momentic tests covering them,
reusing existing tests where they already partially cover a journey. Pass
--dry-run to only discover and log journeys.
explore has two subcommands:
explore diff
Explore a git diff window: the agent diffs a commit range and reports the
journeys that changed.
string
Commit or commit range to explore. Uses
git diff range semantics:
base...head diffs the merge-base of the two refs against head,
base..head diffs base directly against head, and a single commit diffs
that commit against its first parent (commit^). A missing endpoint defaults
to HEAD. When omitted, defaults to the current pull request’s diff window in
CI (GitHub Actions, CircleCI, GitLab, Buildkite, Azure DevOps); otherwise
HEAD~1..HEAD.explore diff accepts every shared option below.
--base <sha> and --head <sha> are deprecated; pass a commit range argument
instead (e.g. main...HEAD). --seed is deprecated; use momentic ai explore latest.explore latest
Seed coverage for the entire app instead of a diff. The explorer maps the whole
product and self-replicates into child explorers, one per surface, so a new
project can go from zero to a baseline of coverage without a diff to anchor on.
Output is labeled as discovered journeys rather than changed journeys.
explore latest accepts the same shared options as
explore diff. It defaults to a 60-minute --timeout.
Shared options
These apply to bothexplore diff and explore latest.
boolean
Only discover and log journeys without building Momentic tests. Building is on
by default. Defaults to
false.string
Custom additional prompt appended to the explorer agent’s instructions.
Repeatable, and combinable with
--prompt-file. The combined instructions are
all --prompt-file contents followed by all --prompt values, each in the
order passed.string
Path to a file whose contents are appended to the explorer agent’s
instructions. Repeatable, and combinable with
--prompt. The combined
instructions are all --prompt-file contents followed by all --prompt
values, each in the order passed. Keeping the prompt in a committed file lets
it live in your repo. See Configure the
agent.string
How specific the proposed test plans should be:
low covers the happy path of
the main flows plus important failure states (e.g. a failed login), medium
covers the happy path of every interaction plus important failure states, and
high covers every flow in depth including the happy path and its different
failure modes. Overrides the project config. Defaults to the config value
(medium if unset). Cannot be combined with --budget.number
Maximum number of tests to generate: the explorer targets at most this many
test plans, prioritising the most important journeys, and stops discovering
flows once the budget is filled. Cannot be combined with
--granularity.boolean
Remove the explorer’s git and filesystem access (
git log/diff, read-file,
grep, find-file). The explorer grounds its analysis in the running app through
a live browser session instead.boolean
Print the explorer result as JSON to stdout instead of the human-readable
summary. The payload includes changed or discovered journeys, test plans, and
any potential product bugs the agent found. The live streaming UI is
suppressed. Defaults to
false.number
default:"15 (60 for latest)"
Maximum number of minutes to run before aborting. On timeout the explorer
stops and emits partial results; build and edit sub-agents are each capped at
two-thirds of this. Defaults to 15 minutes for
explore diff and 60 minutes
for explore latest.boolean
Print a
git apply-ready patch of the authored tests to stdout instead of
applying the configured On successful explore delivery. Use this for
forked-PR runs that cannot open a pull request.-c, --config, -f, --filter, and -p, --parallel flags apply as
they do for triage.
Output behavior
When the agent writes tests, the On successful explore behavior in Settings > Explore decides what happens to them: open a pull request, open a draft pull request, commit directly (except onmain or protected branches), print a git patch, or leave the
changes on disk. Pull requests are pushed to a momentic-explore/ branch.
To run explore on every pull request, see
Author tests from a diff in CI.
bugbash
Run a bug bash: discover user journeys the same way explore does, then verify
each plan in a live browser and report product bugs instead of building tests.
See Bug bash with the explore agent for the
workflow.
bugbash latest maps the whole product and accepts the same
shared options as explore latest, including the 60-minute
default --timeout. By default no tests are authored, so the On successful
explore delivery does not apply; the output is the list of potential bugs,
each with a severity, reproduction steps, and a screen recording when one was
captured.