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

# momentic results

> Upload, merge, view, and check local Momentic test results.

Manage the results directory produced by
[`momentic run`](/cli-reference/momentic/commands/run). Use `upload` after
running with `--upload-results` disabled, `merge` to combine sharded runs,
`view` to inspect runs locally without uploading, and `check` to gate CI on
truly clean results.

```bash theme={null}
npx momentic results upload
```

## `upload`

Upload local test results to the Momentic dashboard.

```bash theme={null}
npx momentic results upload [folder]
```

### Arguments

<ParamField path="[folder]" type="string">
  Folder containing results from `momentic run` or `momentic results merge`.
  Defaults to `test-results`, which matches the default `--output-dir` of
  `momentic run`, so you can usually omit this argument.
</ParamField>

## `merge`

Merge results from multiple sharded runs into a single folder before uploading.

```bash theme={null}
npx momentic results merge <parent folder>
```

### Arguments

<ParamField path="<parent folder>" type="string" required>
  Parent folder of the results to merge. For example, if shards wrote into
  `test-results/shard-1` and `test-results/shard-2`, pass `test-results`.
</ParamField>

### Options

<ParamField path="--output-dir <outputDir>" type="string">
  Directory to write the merged results to. The folder is overwritten if it
  exists.
</ParamField>

## `view`

Launch the local run viewer to inspect results without uploading.

```bash theme={null}
npx momentic results view <results> [runId]
```

### Arguments

<ParamField path="<results>" type="string" required>
  Path to a folder containing a `runs/` subfolder. Defaults to `test-results`.
</ParamField>

<ParamField path="[runId]" type="string">
  Run ID to open, matching a zip file in the `runs/` subfolder. For example, for
  `runs/eed92602-7355-43dc-8d79-1c43029bec26.zip`, pass
  `eed92602-7355-43dc-8d79-1c43029bec26`. When omitted, the viewer opens to the
  run group table.
</ParamField>

### Options

<ParamField path="--port <port>" type="number">
  Port for the local run viewer server. Defaults to `58889`.
</ParamField>

## `check`

Exit non-zero if any non-quarantined run in a results archive did not pass
cleanly. Use it as a CI gate after `merge` to require truly green results.

```bash theme={null}
npx momentic results check <results>
```

A run is considered **not clean** (and the command exits `1`) when it is not
quarantined and any of the following is true:

* its final status is `FAILED` or `CANCELLED`,
* it only passed after an in-run
  [failure recovery](/reliability/failure-analysis), or
* it carries a failure [classification](/reliability/failure-analysis) (any
  category, including ones routed to `heal`/`warn`).

Quarantined runs are always ignored. The command exits `0` only when every
non-quarantined run passed outright with no recovery and no classification.

Pass `--allow-recovered` to treat runs that passed via in-run failure recovery
as clean - they no longer fail the check, while `FAILED`/`CANCELLED` runs and
failure classifications still exit `1`.

### Arguments

<ParamField path="<results>" type="string" required>
  Path to a folder containing a `runs/` subfolder, typically the `--output-dir`
  of a preceding `momentic results merge`.
</ParamField>

### Options

<ParamField path="--allow-recovered" type="boolean">
  Treat runs that passed via in-run failure recovery as clean (exit `0`).
</ParamField>

<ParamField path="--json" type="boolean">
  Suppress progress output and print the check report as JSON. The report
  includes per-run detail for each not-clean run (`uncleanRuns`) and a `summary`
  with descriptive per-category counts: `total`, `clean`, `quarantined`,
  `failed`, `cancelled`, `recovered`, and `classified`. These counts overlap (a
  run can be both recovered and classified), so they do not sum to `total`.
</ParamField>

## Examples

Upload the default results folder:

```bash theme={null}
npx momentic results upload
```

Merge sharded results before uploading:

```bash theme={null}
npx momentic results merge test-results --output-dir test-results/merged
npx momentic results upload test-results/merged
```

View a specific run locally on a custom port:

```bash theme={null}
npx momentic results view --port 59999 my-results eed92602-7355-43dc-8d79-1c43029bec26
```

Gate CI on clean results after merging shards:

```bash theme={null}
npx momentic results merge test-results --output-dir test-results/merged
npx momentic results check test-results/merged
```