Skip to main content

Documentation Index

Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 return NO_FAILURE. 
npx momentic ai classify <runIdOrUrl>

​
Arguments

​
<runIdOrUrl>
string
required
Run ID or full run URL (e.g. https://app.momentic.ai/runs/<runId>). The run must either be uploaded to the dashboard or live in the latest CLI run group under the project output directory.

​
Options

​
--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.
​
-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. Requires a TTY; cannot be combined with --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"
}

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

​
heal

Runs the healing agent over a local results archive from momentic run. The agent investigates failures, attempts to update tests in place, and writes the outcome back to the run group. Failed runs are grouped by shared fixes when possible.
For a copy-paste CI setup and the different integration paths, see Auto-heal failing tests in CI.
npx momentic ai heal <results>

​
Arguments

​
<results>
string
required
Path to a local results archive directory written by momentic run. The directory must contain a run group metadata file.

​
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 heal 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, firefox, or webkit.
​
--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.

​
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. The heal fails if the resource is not reachable in time.

​
CI

​
--timeout-minutes <timeoutMinutes>
number
Maximum total heal 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.

​
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
Heal failed runs from the latest local results directory: 
npx momentic ai heal ./test-results
Heal only quarantined failures with two parallel sessions: 
npx momentic ai heal ./test-results --only-quarantined --parallel 2
Heal everything except a couple of known-flaky tests: 
npx momentic ai heal ./test-results --exclude "checkout flow" "^Legacy "