> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# ancha explain

> Explain why trials of a finished run failed: crashes and timeouts with the end of the agent's log, expected versus actual and the API calls behind each failed check, coverage gaps, and what the agent's environment withheld.

`ancha explain` reads a finished run and prints, for each failed trial, what went wrong and the evidence behind it. Read it before changing the agent.

```bash theme={null}
ancha explain [options] <run>
```

| Argument | Description |
| - | - |
| `run` | Run id (run\_…) or "latest" |

| Option | Description |
| - | - |
| `--scene <id>` | Only this scene |
| `--trial <n>` | Only this trial |
| `--out <dir>` | Where run directories are (default: .ancha/runs) |

## Example

```bash theme={null}
ancha explain latest
```

```text Output theme={null}
starter  trial 1  ✗ pagerduty_access
  expected: agent calls * /services*
  actual:   never called; agent made 3 call(s)
  why:      The agent never made a call matching "* /services*". Its calls were: GET /api/conversations.list, GET /repos/acme/starter, GET /api/v1/dashboard.
  trace:
    #1 agent GET /api/conversations.list -> 200
    #2 agent GET /repos/acme/starter -> 200
    #3 agent GET /api/v1/dashboard -> 200

environment: 72 variables from this shell were withheld from the agent. If it needs one (a provider key, say), pass it with --pass-env NAME or list it under agent.pass_env in ancha.yaml.

Patterns are "<METHOD> <PATH>" matched against the service-relative path, and * is a wildcard.

next: ancha baseline save before --from run_20261031-234205_7570556079db03cd, then fix the agent, then ancha run --compare before
```

It reports, in order:

1. Harness issues: a part of Ancha failed, so the trial is invalid and does not count as an agent failure.

2. Agents that crashed or timed out, with the end of `agent.log`:

   ```text Output theme={null}
   starter  trial 1  ✗ agent exited with code 3 after 81ms
     log:  /path/to/project/.ancha/runs/run_20261031-234929_56e8ff2edbb29618/trial-starter-1/agent.log, last 2 line(s):
       starting
       boom: something broke
   ```

3. Each failed check: what was expected, what happened, and the agent's calls behind it.

4. Coverage gaps, with or without `--strict`: calls to endpoints a replica does not implement, with the replica's answer. The agent's call may be right; check `ancha twins coverage <tool>` before changing it.

   ```text Output theme={null}
   starter  coverage gap: the agent called POST /api/chat.scheduleMessage, which the slack twin doesn't implement; it answered unknown_method in the vendor's error shape. The agent's call may be right: see ancha twins coverage slack
   ```

5. How many of your shell's variables were withheld from the agent, when it ran on this computer. If it needs one, such as a provider key, pass it with `--pass-env NAME` or `agent.pass_env`. See [`ancha run`](https://docs.ancha.io/cli/run#what-the-agent-gets).

A run with nothing to explain prints `no failed checks to explain`.

## JSON output

`ancha explain latest --json` prints one object:

| Field | Contents |
| - | - |
| `runId` | The run. |
| `failures` | One entry per failed check: `sceneId`, `trial`, `check`, `expected`, `actual`, `explanation` and `traceExcerpt` (the agent's calls with `seq`, `source`, `method`, `path`, `status`). |
| `agentIssues` | Crashes, non-zero exits and timeouts, with `exit`, `exitCode`, `realMs`, `log` and `logTail`. |
| `harnessIssues` | Problems Ancha itself had during a trial. |
| `coverageGaps` | Each with `service`, `method`, `path`, `count`, the replica's `status` and `error`, and a `hint`. |
| `agentEnvironment` | `target` (`host`, `container` or `external`), and for this computer `inherited` and `withheld` counts. |
| `gradingWarnings` | Present when a check produced a warning. |
| `next` | The commands to run next, such as `fix the agent` and `ancha run --compare before`. |

`ancha schema explain` prints the schema.

## Exit codes

`explain` exits `0` whenever it can read the run, even if the run failed. Use the exit code of `ancha run` for the verdict. An unknown run ID exits `2`:

```text Output theme={null}
error[USAGE]: unknown run "run_nope"
hint: see .ancha/runs/
```

## Where to look next

`explain` shows the calls behind a failure. For request and response bodies, open `trace.jsonl` in the trial's directory; for the final records, `state.json`. Both paths are in the run summary under `trialsDetail[].dir`.


## Related topics

- [ancha schema](https://docs.ancha.io/cli/schema.md)
- [Troubleshooting](https://docs.ancha.io/troubleshooting.md)
- [For coding agents](https://docs.ancha.io/coding-agents.md)
- [ancha run](https://docs.ancha.io/cli/run.md)
- [Linear](https://docs.ancha.io/tools/linear.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.