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

> Write a test saved from a production trace into this project. A trace with no saved test gets one.

`ancha pull` writes a test your workspace saved from a production trace into `scenes/from-traces/<name>/`, where `ancha run` finds it. Name a trace that has no saved test yet and `ancha pull` saves one first. With `--answer`, it saves a new version with your answers to the test's questions, then writes that.

```bash theme={null}
ancha pull [options] <id>
```

| Argument | Description |
| - | - |
| `id` | A test or a trace: its id, its first 8 characters, or the trace id your tracing tool shows |

| Option | Description |
| - | - |
| `--dest <dir>` | Where the tests go (default: `scenes/from-traces`) |
| `--answer <question>=<value>` | Answer one of the test's questions, saving a new version first. Repeat it for more. |
| `--expect <what went wrong>` | Say in a sentence what the agent did wrong in production, saving a new version with a check for it. |
| `--force` | Overwrite `scene.yaml` even if it has changes besides checks you added |

Sign in with `ancha login` first, or set `ANCHA_SERVER_URL` and `ANCHA_API_KEY`.

## Files

| File | Holds |
| - | - |
| `scene.yaml` | The test: what the agent is asked, its tools, starting data, what happens during the run, and the checks. Run it with `ancha run`. |
| `observations.jsonl` | Every call production made to the agent's own tools, with its answer. |
| `production.jsonl` | Production's run: its input, its tool calls and its answer. |
| `production.json` | What production did on each check: `passed`, `failed` or `unknown`. `ancha run` computes the unknown ones from `production.jsonl`, also for checks you add, and compares with it. |
| `questions.json` | What one trace cannot settle, each with the default the test uses. |
| `provenance.json` | Every part of the test, and whether it was seen in the trace (`observed`, with its span ids), `inferred`, or `missing`. |

When your `ancha.yaml` lists `scenes:` globs that do not include the new test, `ancha pull` prints a note with the glob to add.

## Answers

[`ancha traces show`](https://docs.ancha.io/cli/traces) lists a test's questions, each with how to answer it:

| Question | `--answer` value |
| - | - |
| `task` | What the agent is told, in your words. You can always answer it, even when the trace said it and nothing asks. |
| `tools.mcp` | The tools your agent reaches over MCP, comma-separated, or `all` or `none` |
| `tools.simulate_writes` | The writes a test may simulate when your agent makes one production never made, comma-separated, or `all` or `none` |
| `checks.success` | What the agent should have done, in your words, when nothing in the trace says what went wrong |
| `deploy-…` | Seconds until production has a merge, such as `60`, or `none` when nothing deploys |
| `recovery-…` | `floor=<earliest second the problem can end>,recovery=<seconds it then takes>`; either part alone works |
| `fix-…` | `undo` when undoing the change the question names ends the problem, or `self=<second>` when it ends on its own |

A value can also be the JSON the console sends, such as `'{"floor":140,"recovery":10}'`. Answers add to the test's earlier answers; `<question>=default` drops one. Questions with no `--answer`, such as issues your agent never read, are answered in `scene.yaml`.

## Pulling again

Pull a test again to get a newer version. Checks you added to `scene.yaml` by hand carry over to the new version. Any other change to `scene.yaml` would be lost, so `ancha pull` stops before it saves or writes anything and says so; move the change into a check of your own, or pass `--force` to overwrite the file. `ancha pull` tells the two apart with the `# ancha pull:` line at the top of `scene.yaml`, so keep that line.

## Example

```bash theme={null}
ancha pull fc7f4f10 --answer tools.mcp=get_deploy_status,rollback,list_issues --expect "it declared the incident resolved on a status measured before the rollback"
ancha pull 4735f9ca
ancha run scenes/from-traces/trace-4735f9ca/scene.yaml
# production deploys in about a minute, and the problem cannot end before 140 seconds:
ancha pull 4735f9ca --answer deploy-repo_orders=60 --answer recovery-problem=floor=140,recovery=10
```

The run ends with a comparison against production, check by check. See [From a production trace to a failing test](https://docs.ancha.io/guides/rebuild-from-traces.md).


## Related topics

- [ancha run](https://docs.ancha.io/cli/run.md)
- [ancha import](https://docs.ancha.io/cli/import.md)
- [ancha traces](https://docs.ancha.io/cli/traces.md)
- [From a production trace to a failing test](https://docs.ancha.io/guides/rebuild-from-traces.md)
- [CLI overview](https://docs.ancha.io/cli/overview.md)


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