> ## 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 import > Turn a production trace file into a scene on your computer, and answer the questions one trace can't settle. Use `ancha import --offline` to turn a trace of a production run into a scene for [`ancha run`](https://docs.ancha.io/cli/run). It runs on your computer and uploads nothing. ```bash theme={null} ancha import --offline trace.otlp.jsonl ``` The file is an Ancha Trace IR file (`.jsonl`), or an OTLP JSON export whose spans carry the request and response bodies of the agent's calls to its tools. Hosted workspaces don't take traces, so pass `--offline`. A trace that holds only model calls and tool-call spans (a tool's name, arguments and result), as most tracing setups record them, has no such requests. The import then stops with `the trace has no API calls or webhooks Ancha can read` and exits `2`. ## Options | Option | Description | | - | - | | `--offline` | Make the test on this computer. Nothing is uploaded. | | `--dest ` | Where the tests go. Default `scenes/from-traces`. | | `--answer ` | Answer one of the test's questions. Repeat for more. | | `--force` | Replace a `scene.yaml` that is already there, even if it has changes besides checks you added. | | `--json` | Print one JSON object. | ## Output ```text Output theme={null} wrote scenes/from-traces/trace-c73e4ce5/scene.yaml from trace.otlp.jsonl, on this computer (nothing was uploaded) 4 observed, 4 inferred, 1 missing; provenance in provenance.json questions (answer with --answer =, then import again with --force; a default repeats what production did, so answer the ones about what went wrong): task: What is the agent told when it starts? default: Handle what arrives the way you do in production. app.auth: What Authorization header do the app's own scheduled calls carry in tests? (the trace never records headers) default: none ``` The scene's folder, `trace-`, holds `scene.yaml` and `provenance.json`. The provenance file records which facts came from the trace, which Ancha inferred and which are missing. With `--json`, the result has `scene` (the path written), `summary` (`trace`, `agent`, `records`, `observed`, `inferred`, `missing` and `questions` counts) and `questions`, each with `id`, `question`, `options` and `default`, and `setup`, each with `call` and `count`. For an app, the output also lists its own setup: the calls production made before the first event the test replays. ```text Output theme={null} warning: 3 calls came before the first event the test replays, the app's own setup: gmail POST /gmail/v1/users/me/watch, gmail POST /gmail/v1/users/me/labels ×2 the test has them only if the app makes them when it starts, or the start script or an app_calls entry does (ancha docs apps) ``` ## Answer the questions One trace can't settle everything, such as what the agent is told when it starts or which header the app's scheduled calls carry. Each question has a default, and the scene uses it until you answer. A default repeats what production did, so answer the questions about what went wrong: ```bash theme={null} ancha import --offline trace.otlp.jsonl --force --answer app.auth="Bearer test-cron-secret" ``` Then run the scene against the version that failed in production. It should fail the same way. See [Test an app](https://docs.ancha.io/guides/test-an-app.md#turn-a-production-trace-into-a-test) for what a trace can't show. ## Compare an attempt with production When the scene doesn't fail the way production did, compare the calls. `ancha traces diff` reads the 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 `/`; 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. ## Exit codes | Code | Meaning | | - | - | | `0` | The scene was written. | | `2` | The file can't be read or has no API calls or webhooks Ancha can read, or a `scene.yaml` is already there and `--force` is missing (`USAGE`). | ## Traces in a workspace `ancha traces`, `ancha traces show ` and `ancha pull ` work with a workspace that takes traces from your agents. Hosted workspaces at app.ancha.io don't take traces: `ancha traces` stops with `this workspace does not take traces yet`. Use `ancha import --offline` with a trace file instead. To write an attempt of your own run in the same format, use [`ancha runs export`](https://docs.ancha.io/cli/runs#export-a-run-as-a-trace). ## Related topics - [For coding agents](https://docs.ancha.io/coding-agents.md) - [Changelog](https://docs.ancha.io/changelog.md) - [CLI overview](https://docs.ancha.io/cli/overview.md) - [Introduction](https://docs.ancha.io/index.md) - [Test an app](https://docs.ancha.io/guides/test-an-app.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.