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. If omitted, no test-count cap applies.
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.
number
default:"180"
Maximum selection time in seconds. Minimum: 60. The selector reserves time to
finalize gathered evidence before the deadline. If it cannot recover a
selection, it returns a run-all fallback. Slow billing or telemetry does not
discard a completed selection.
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, --git-commit, or --from-quarantine. 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
Heal the active quarantine backlog instead of a specific results set. Walks
quarantined tests earliest-quarantined first, replaying each one’s most recent
failed run. Tests whose stored heal status is Unhealable are skipped with
their diagnostics printed; clear the heal status from the Quarantine
board to retry one. Honors
--exclude.
Cannot be combined with --only-quarantined or --skip-quarantined.number
Maximum number of quarantined tests to attempt in one
--from-quarantine
invocation. Scanning stops as soon as the budget is filled and the summary
reports how many tests were not attempted. Must be a positive integer.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
default:"false"
Skip quarantined tests during triage. Disabled by default, so quarantined
failures are included in healing.
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.