> ## Documentation Index > Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt > Use this file to discover all available pages before exploring further. # mutagent reports, findings, triage > Store Helix's evaluation and diagnosis reports in your workspace, track the findings they raise, and file problems about an agent. When Helix evaluates or diagnoses an agent, it writes a report: what was checked, what failed, and why. These commands keep those reports in your workspace, so your team can read them, mark them reviewed, and follow each failure until it is fixed. * A **report** is one run's result: an evaluation, a diagnosis, a discovery run, or a person's review. * A **finding** is one failing or undecided criterion from an evaluation report. Findings are created for you when you store an evaluation report. * A **triage item** is a problem you file about an agent, skill or workflow, for example after a customer complaint. **Before you start:** [install the CLI](/cli/installation), [sign in](/cli/commands/login) (`MUTAGENT_API_KEY= mutagent login --json` for a coding agent), and select the workspace with `mutagent workspaces use `. To push a report, Helix must be installed ([mutagent install](/cli/commands/install)), because `helix-cli`, which ships with it, publishes the report first. Reads (`list`, `show`) need no confirmation. Every write (`push --replace`, `review`, `retract`, `set-status`, `triage file`) changes shared workspace data: a coding agent confirms with the person before it runs one. ## A worked example ```bash theme={null} helix-cli report publish runs/42/report.html runs/42/report.client.html mutagent reports push runs/42 --kind evaluator mutagent findings list --status open mutagent reports review mutagent findings set-status resolved ``` 1. `helix-cli report publish` publishes the report Helix rendered. `reports push` stores the evaluation report from the run folder `runs/42`. Storing it creates a finding for every criterion that failed or could not be decided. 2. `findings list` shows the open findings. 3. After someone has read the report, `reports review` marks it reviewed. 4. When the fix is in, `findings set-status … resolved` closes the finding. ## mutagent reports push Store a report in the workspace. ```bash theme={null} mutagent reports push --kind --json ``` | Argument or flag | What it does | | - | - | | `` | The run folder (with `render-input.json` and one `*.client.html`), or the published HTML file. | | `--kind ` | Required. `evaluator`, `diagnostics`, `discovery`, or `hitl` (a person's review of a run). | | `--subject ` | The agent, skill or workflow the report is about. | | `--run-id ` | The run that produced it. The default is the run ID in the report. Not with `--kind hitl`. | | `--session-ref ` | The Helix session reference. | | `--title ` | The title. The default is the report's own title. | | `--render-input ` | The render-input JSON. The default is `render-input.json` next to the HTML. | | `--replace` | Replace the report already stored for this run and kind. It keeps its ID and is marked unreviewed. Not with `--kind hitl`. | Only reports published with `helix-cli report publish` are accepted. Publishing removes personal data from the report. A file that was not published is refused with `REPORT_NOT_PUBLISHED` (exit 1), and nothing is sent. Run the publish command the error names; do not edit the HTML by hand. A report published by an older `helix-cli` must be published again. Success: exit code `0`. With `--json`: `{ success, created, replaced, report, _links, _directive }`. Pushing the same run and kind twice stores nothing new: the second push returns `created: false` and `replaced: false` with the first report. That is a success, so a script can retry safely. A `hitl` report has no run ID, so every `hitl` push stores a new report. ## mutagent reports list, show, review, retract ```bash theme={null} mutagent reports list --kind evaluator --subject support-bot mutagent reports show --html report.html mutagent reports review mutagent reports retract --force ``` | Command | What it does | | - | - | | `reports list` | The workspace's reports, newest first. Filter with `--subject`, `--kind`, `--run-id` or `--session-ref`; page with `--cursor`. | | `reports show ` | One report. `--html ` saves the report page so you can open it in a browser. | | `reports review ` | Mark the report reviewed. `--undo` marks it unreviewed. | | `reports retract --force` | Delete the report, its findings and its page. It never asks: without `--force` (or `--yes`) it refuses with `CONFIRMATION_REQUIRED`. Retracting a report that is already gone succeeds. | With `--json`, `reports list` returns `{ reports, count, nextCursor }`; `nextCursor` is `null` on the last page. An unknown report ID is `REPORT_NOT_FOUND` (exit 1). ## mutagent findings ```bash theme={null} mutagent findings list --status open --subject support-bot mutagent findings set-status resolved ``` | Command | What it does | | - | - | | `findings list` | Findings, newest first. Filter with `--status` (`open`, `in-diagnostics`, `resolved`), `--subject`, `--run-id` or `--report`. | | `findings set-status ` | Close a finding, or open it again. Setting the status it already has succeeds and changes nothing. | With `--json`, `findings list` returns `{ findings, count }` in one page. `set-status` is refused (exit 1) with `STATUS_SET_BY_ROUTING` if you ask for `in-diagnostics`, `ILLEGAL_STATUS_TRANSITION`, `STATUS_CHANGED` (someone changed it first: list it again before you retry) or `FINDING_NOT_FOUND`. Each finding shows the criterion that failed, its severity, whether it blocks a release (`gating`), and the report it came from. ## mutagent triage File a problem about an agent, skill or workflow, then follow it to a fix. ```bash theme={null} mutagent triage file --subject support-bot \ --title "Quotes the wrong refund window" \ --body "Told a customer 60 days; the policy is 30." ``` The command first prints exactly what it will send: the workspace, every field and the full text. In a terminal it then asks, and sends only if you say yes. Under `--json`, in CI or in a pipe, it sends nothing until you run it again with `--yes`. For a coding agent: 1. Run it with `--json` and without `--yes`. It returns `sent: false`, `consentRequired: true`, a `preview` and `next`, and exits `0`. 2. Show `preview` to the person and ask whether to file it. 3. Only on a yes, run `next[0]` (the same command with `--yes`). It returns `sent: true` and the `item`. | Flag | What it does | | - | - | | `--subject ` | Required. The agent, skill or workflow the problem is about. | | `--title ` | Required. One line. | | `--body ` | Required. What happened, or `@path` to read it from a file. | | `--severity ` | `CRIT`, `HIGH`, `MED` or `LOW`. | | `--subject-kind ` | `agent`, `skill`, `workflow` or `multi-agent-system`. | | `--repo ` | The GitHub repository the subject lives in. | | `--source ` | Who is filing: `chat` (the default), `trace-score`, `external` or `mention`. | | `-y, --yes` | Send without asking. Use it only after you have read the preview. | | Command | What it does | | - | - | | `triage list` | Triage items, newest first. Filter with `--status` and `--subject`. | | `triage show ` | One item, with its full text. | | `triage set-status ` | Close an item, or open it again. It is refused like `findings set-status`; an unknown ID is `TRIAGE_NOT_FOUND`. | There is no delete for triage items: an item is resolved, not removed. ## If it fails | Exit code or error | Fix | | - | - | | `3` (`AUTH_REQUIRED`, `WORKSPACE_REQUIRED`) | [Sign in](/cli/commands/login), then `mutagent workspaces use `. | | `2` (`AUTH_EXPIRED`, `INVALID_API_KEY`) | Sign in again, or set a valid `MUTAGENT_API_KEY`. | | `REPORT_NOT_PUBLISHED` (exit 1) | Run the `helix-cli report publish` command in `suggestedAction`, then push again. | | `CONFIRMATION_REQUIRED` (exit 1) | `retract` needs `--force`. Confirm with the person first. | | `STATUS_CHANGED` (exit 1) | Someone changed the status first. Read it again and ask before you retry. | On any other error, run the command in `suggestedAction` once; do not retry blind. See [CLI errors](/cli/errors). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.