Skip to main content
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, sign in (MUTAGENT_API_KEY=<key> mutagent login --json for a coding agent), and select the workspace with mutagent workspaces use <workspace-name>. Only a report Helix published can be pushed. Helix publishes each final report, and in a cloud sandbox it also pushes it; to push a report Helix published from a local run, run mutagent reports push <run-dir>. Reads (list, show) need no confirmation. Every write (push --replace, update, review, retract, set-status, triage file) changes shared workspace data: a coding agent confirms with the person before it runs one.

A worked example

Evaluate writes each run to .mutagent/evaluator/<run-id>/: the report HTML and its render-input.json.
  1. Helix publishes a copy of the report with personal data removed (report.client.html). reports push stores the evaluation report from the run folder. 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.
Only reports Helix published are accepted. Publishing removes personal data from the report. A file Helix did not publish (or published with an older version) is refused with REPORT_NOT_PUBLISHED (exit 1), and nothing is sent: rerun the stage in Helix. Do not edit the HTML by hand. 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. A report can be tied to a Factory entry, the spec version and build it was made against, and the stage run it is evidence for:
  • With --stage-run, the report inherits the run’s entry, spec version and build. On your machine, pass the links you have as flags.
  • A closed run is refused with STAGE_RUN_FINISHED. That run already records the stage: push without --stage-run, pass --subject, --spec-version and the build flags yourself, and do not record the stage again. To link a report to its run, push it before mutagent factory stage finish, or attach it there with --report.
  • A --build-rev with no --build-target takes the entry’s only target. If the entry has several, the push is refused with BUILD_TARGET_REQUIRED: add --build-target.
  • In a cloud sandbox with no API key, the sandbox’s own token uploads the report to the sandbox’s workspace. With no --stage-run, the report is attached to the session’s open stage run, with its entry, spec version and build; pass flags only to override them.

mutagent reports update

Change a pushed report’s title, verdict or Factory links. The report’s content stays; to change the content, push it again with --replace.
Only the fields you pass change. With --json: { success, report, changed, _links, _directive }; changed lists the fields sent. Marking a report reviewed is reports review. Updating needs the editor or admin role, or, in a cloud sandbox, a report that sandbox pushed. A coding agent confirms with the person first.

mutagent reports list, show, review, retract

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

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.
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.
There is no delete for triage items: an item is resolved, not removed.

If it fails

On any other error, run the command in suggestedAction once; do not retry blind. See CLI errors.