> ## 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, 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` 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 traces

> List the production traces your agents sent, and preview the test a trace makes before you save it.

`ancha traces` lists the traces in your workspace, newest run first. `ancha traces show` previews the test one trace makes: what the agent is told, the world, the checks with what production did, and the questions one trace cannot settle. Nothing is saved until you run [`ancha pull`](https://docs.ancha.io/cli/pull).

```bash theme={null}
ancha traces [options]
ancha traces show <id>
ancha traces diff <trace file> [attempt]
```

| Option | Description |
| - | - |
| `--failed` | Only traces where production failed a check |
| `--passed` | Only traces where production passed every check |
| `--agent <name>` | Only this agent's traces |
| `--tool <tool>` | Only traces that called this tool, such as `slack` |
| `--env <name>` | Only traces from this deployment environment: OpenTelemetry's `deployment.environment`, or Langfuse's environment |
| `--limit <n>` | At most this many (default: 20) |

`ancha traces show` takes a trace's id, its first 8 characters, or the trace id your tracing tool shows. Sign in with `ancha login` first, or set `ANCHA_SERVER_URL` and `ANCHA_API_KEY`. With `--json`, both print the workspace's data as one JSON object.

## Example

```text theme={null}
$ ancha traces --failed
2 traces, newest first:
  4735f9ca  2026-10-21 13:59 UTC  acme-oncall  datadog, github, slack, pagerduty  production failed 3 checks  test saved
  764cfbcc  2026-10-21 13:59 UTC  acme-oncall  datadog, github, slack, pagerduty  production failed 2 checks  test saved

$ ancha traces show 4735f9ca
trace 4735f9ca (85ff075cdaec081c188c079b0eab6abd): acme-oncall, started 2026-10-21 13:59 UTC, 74 records
what arrived:
  datadog: 14 API calls, rebuilt
  github: 9 API calls, rebuilt
  slack: 7 API calls, rebuilt
  pagerduty: 6 API calls, rebuilt
  17 model calls, with what the agent was told
the test it makes:
  the agent is told: Orders requests are failing after a deploy. …
  the world:
    Slack: #orders-incident, 1 person, 1 earlier message
    GitHub: acme/orders, 2 commits on main
    At 91s, someone posts "Status request: what is the current customer impact, …"
    A merge to the default branch deploys production in 15s
    The problem is on from the start; it ends when production has the fix in config/runtime.ts, not before 128s, then recovers over 20s
  checks:
    answered-msg-status-request     failed in production  (the agent answers "Status request: …" in its thread)
    problem-resolved                failed in production  (the problem ends)
  questions one trace cannot settle (the test runs with each default until you answer):
    deploy-repo_orders: What happens when a pull request merges to main in acme/orders?
      default: It deploys production in about 15 seconds
      answer: ancha pull 4735f9ca --answer deploy-repo_orders=<seconds until production has the merge>, or deploy-repo_orders=none
not saved yet: ancha pull 4735f9ca saves it as a test and writes it here
```

A tool marked `not rebuilt yet` is left out of the test. A note under **what arrived** says what a trace is missing, such as response bodies or what the agent was told, and how to send it. See [From a production trace to a failing test](https://docs.ancha.io/guides/rebuild-from-traces.md).

## Compare an attempt with production

When a test doesn't fail the way production did, compare the calls. `ancha traces diff` reads a trace file and one attempt of a finished run on this computer:

```bash theme={null}
ancha traces diff trace.otlp.jsonl latest/trial-tom-replies-1
```

```text Output theme={null}
production trace.otlp.jsonl: 14 calls; attempt run_20261107-052607_e3cc66e6ab5307b4/trial-tom-replies-1: 14 calls
only in production:
  gmail GET /gmail/v1/users/me/threads/:id
  gmail POST /gmail/v1/users/me/drafts
only in the attempt:
  gmail GET /gmail/v1/users/me/history ×2
the order parts at call 11: production gmail GET /gmail/v1/users/me/threads; the attempt gmail POST /gmail/v1/users/me/threads/:id/modify
```

Calls compare by tool, method and path, with the record IDs in a path written `:id`. The attempt is `<run id or latest>/<trial directory>`; a run alone means its first attempt. With `--json`, the result has `production` and `attempt` (each with its call count), `onlyInProduction` and `onlyInAttempt` (each call with its `count`) and `firstDifference` (`index`, `production` and `attempt`), which is `null` when the orders match. It exits `0` either way.

A call production made and the attempt didn't, such as labels created at setup or a settings read, usually points at what the seed lacks. For the agent's own tools, `ancha explain <run> --trial <n>` lists every answer that was not production's.


## Related topics

- [Traces](https://docs.ancha.io/cloud/traces.md)
- [Trace IR](https://docs.ancha.io/reference/trace-ir.md)
- [ancha runs](https://docs.ancha.io/cli/runs.md)
- [ancha import](https://docs.ancha.io/cli/import.md)
- [ancha pull](https://docs.ancha.io/cli/pull.md)


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