Skip to main content
AI-powered subcommands that operate on existing test runs. Use these to triage failures or attach AI-generated metadata to runs in CI. 
npx momentic ai classify <runIdOrUrl>

​
classify

Classify the result of a test run. The agent inspects step results, screenshots, and error details and returns a category with reasoning. Only failed runs are classified; passing runs are skipped. Provide exactly one selector: --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. 
npx momentic ai classify --run-id <runIdOrUrl>
npx momentic ai classify --run-group-id <runGroupIdOrUrl>
npx momentic ai classify --git-commit <sha>

​
Options

​
--run-id <runIdOrUrl...>
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.
​
--run-group-id <runGroupIdOrUrl>
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>).
​
--git-commit <sha>
string
Classify every failed run recorded at the given git commit SHA, across all run groups.
​
--skip-classified
boolean
When targeting a run group or commit, skip runs that already have a saved classification. Useful for resuming a partially-completed batch.
​
-p, --parallel <parallel>
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.
​
--output-format <format>
string
Output format for the classification. Defaults to text. Use json to print only the structured payload to stdout.
​
--quiet
boolean
Suppress the agent’s streamed reasoning. Redundant when --output-format json is set.
​
--save
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.
​
-i, --interactive
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: 
Classification: BUG
Reasoning: The checkout button was disabled due to a validation error that appeared after the address step...
Confidence: high
Recoverable: RECOVERABLE
Pass --output-format json to emit a machine-readable payload instead: 
{
  "category": "BUG",
  "reasoning": "The checkout button was disabled due to a validation error...",
  "recoverable": "RECOVERABLE",
  "confidence": "high"
}
When targeting a run group or commit, the text output shows one row per run plus an aggregated summary of category counts and any failures. The json payload is an array, one entry per run; entries that failed to classify carry an error field instead of a classification: 
[
  {
    "runId": "<runId>",
    "testName": "Checkout",
    "classification": {
      "category": "BUG",
      "recoverable": "RECOVERABLE",
      "confidence": "high"
    }
  },
  { "runId": "<runId>", "testName": "Login", "error": "Run archive not found" }
]
Failures do not stop the batch; remaining runs are still classified and the errors are reported in the summary. Re-run with --skip-classified to retry only the runs that did not complete.

​
Categories

​
NO_FAILURE
enum
No failures, all attempts passed.
​
APPLICATION_CHANGE
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.
​
BUG
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.
​
TEST_AUTHORSHIP
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.
​
TEST_SETUP
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).
​
INFRA
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.
​
MOMENTIC_ISSUE
enum
An issue with Momentic’s own execution (e.g. incorrect cache entries, unexpected locator redirects, obvious AI hallucinations).
​
OTHER
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.
Triage can take a while. When you only need to know which runs failed (not to repair them), use momentic results check over the same results folder. It reports the failed, canceled, and quarantined runs so you can decide what to do.
npx momentic ai triage [results]
npx momentic ai triage --run-group-id <runGroupIdOrUrl>
npx momentic ai triage --run-id <runIdOrUrl>
npx momentic ai triage --git-commit <sha>
Provide exactly one selector: a local [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

​
<results>
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

​
--run-group-id <runGroupIdOrUrl>
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.
​
--run-id <runIdOrUrl...>
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.
​
--git-commit <sha>
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.
​
--dry-run
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.
​
--on-heal-success <behavior>
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 Healing setting for this run.
​
--on-heal-fail <behavior>
string
What happens to tests the agent cannot fix. Accepts warn, fail, or quarantine. Overrides the On failed heal Healing setting for this run.
​
--json
boolean
Suppress progress output and print the triage result as JSON.
​
--no-upload
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

​
-c, --config <config>
string
Path to the Momentic configuration file. Defaults to momentic.config.yaml in the current directory.
​
-f, --filter <filter>
string
When using workspaces, load the project whose name matches the filter.
​
-p, --parallel <parallel>
string
Number of healing attempts to run in parallel. Each attempt opens its own browser session. Defaults to 1.
​
--limit <limit>
number
Abort when the number of healable failed runs exceeds this threshold. Must be a positive integer.
​
--exclude <excludePatterns...>
array
Exclude tests whose name 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 test name for that test to be skipped.

​
Environment

​
--env <env>
string
Environment to run replays in. Overrides any environment configured on the test itself.
​
--url-override <urlOverride>
string
Override the base URL of the test or environment during the replay.
​
--custom-headers <customHeaders...>
array
Custom headers to include in the replay. Specify multiple headers separated by spaces.
​
--input-csv <inputCsv>
string
CSV file containing input data for the replay. Each row is used as input for a separate run.

​
Browser

​
--browser <browser>
string
Override the browser used for replays. Accepts chromium, chrome, or chrome-for-testing.
​
--headful-browser [headfulBrowser]
boolean
Launch healing browser sessions headfully by default. Useful for visually watching the agent work. Env: MOMENTIC_HEADFUL_BROWSER.
​
--pixel-ratio <pixelRatio>
number
Device pixel ratio for the healing browser. Set to 2 on macOS Retina or other HiDPI displays.

​
Caching

​
--save-cache
boolean
Always save updated step caches after a successful heal, even on the main and other protected Git branches.
​
--disable-cache
boolean
Disable step caches entirely. Steps run without cached data and no caches are saved.
​
--regenerate-heal
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

​
--only-quarantined
boolean
Only attempt to heal quarantined tests. Failed runs outside quarantine are ignored.
​
--exclude <excludePatterns...>
array
Exclude tests whose project-relative file paths match any of the provided regex patterns.

​
Setup

​
--start <start>
string
Command to run before the replay begins. Useful for booting a local dev server.
​
--wait-on <waitOn>
string
Resource to wait for before the replay begins. Accepts anything supported by wait-on.
​
--wait-on-proxy <waitOnProxy>
string
HTTP proxy used when polling --wait-on. Provide the full URL including protocol, optional credentials, host, and port.
​
--wait-on-timeout <waitOnTimeout>
number
Timeout (in seconds) for --wait-on. Defaults to 60. Triage fails if the resource is not reachable in time.

​
CI

​
--timeout-minutes <timeoutMinutes>
number
Maximum total triage time, in minutes. When reached, in-flight healing attempts stop and the current results are flushed.
​
--quiet
boolean
Suppress the agent’s streamed reasoning.
​
-y, --yes
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 is warn, 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 is fail or quarantine, or delivering an accepted repair failed (e.g. opening the pull request errored), or the triage run itself errored out.
Configure On failed heal in Settings > Healing.

​
explore

The explore agent is in beta and may change.
For the conceptual overview, see the Explore agent guide. Run the explorer agent over a git diff window. It reads the diff between two refs, identifies user-facing changes (including backend changes that surface to the user), and reports the user journeys that changed. With --build it also opens a live browser session and authors or edits Momentic tests to cover them, reusing existing tests where they already partially cover a journey. 
npx momentic ai explore --base main --head HEAD --build

​
Options

​
--base <sha>
string
Base git ref to diff against (branch name, tag, or SHA). Defaults to the current pull request’s base when running in CI (GitHub Actions, CircleCI, GitLab, Buildkite, Azure DevOps); otherwise HEAD~1.
​
--head <sha>
string
Head git ref to diff. Defaults to the current pull request’s head when running in CI; otherwise HEAD.
​
--build
boolean
Build Momentic tests for each discovered journey in a live browser session. When omitted, the agent only discovers journeys and logs them. Defaults to false.
​
--prompt <text>
string
Custom additional prompt appended to the explorer agent’s instructions. Overrides --prompt-file when both are provided. Can also be set as a default in Settings > Explore.
​
--prompt-file <path>
string
Path to a file whose contents are appended to the explorer agent’s instructions. Overridden by --prompt when both are provided.
The standard -c, --config, -f, --filter, and -p, --parallel flags apply as they do for triage.

​
Output behavior

When --build 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 on main 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.

​
Examples

Classify a local run by ID and print JSON for downstream tooling: 
npx momentic ai classify eed92602-7355-43dc-8d79-1c43029bec26 --output-format json
Classify an uploaded run by URL and persist the result: 
npx momentic ai classify https://app.momentic.ai/runs/eed92602 --save
Classify a run, then keep the chat open for follow-up questions: 
npx momentic ai classify https://app.momentic.ai/runs/eed92602 -i
Triage failed runs from the latest local results directory: 
npx momentic ai triage ./test-results
Triage only quarantined failures with two parallel sessions: 
npx momentic ai triage ./test-results --only-quarantined --parallel 2
Triage everything except a couple of known-flaky tests: 
npx momentic ai triage ./test-results --exclude "checkout flow" "^Legacy "
Preview the triage plan without changing tests or uploading the local archive: 
npx momentic ai triage ./test-results --dry-run --no-upload
Discover the user journeys changed by a pull request, without building tests: 
npx momentic ai explore --base main --head HEAD
Build tests for the journeys changed since the last commit: 
npx momentic ai explore --build