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

> Save the setup of a completed ancha agent run as a reusable test with pinned scenario and data versions, and run it again against new agent code.

`ancha test` saves what an `ancha agent run` used, the agent, scenarios, data versions, attempts and seed, so you can run exactly the same thing after changing the agent. For playground tests, see [`ancha playground`](https://docs.ancha.io/cli/playground#saved-tests).

## ancha test new

```bash theme={null}
ancha test new [options] <intent>
```

Drafts a test from one sentence: who starts it, what ends it, and checks on what people learn, decide and are told. The draft is validated against the world before it's written. It calls a model: your `OPENROUTER_API_KEY`, or your workspace's model credit when you're logged in.

| Option | Description |
| - | - |
| `--world <id>` | World file in ancha/worlds (default: the only one) |
| `--id <id>` | Test id (default: from the sentence) |
| `--out <dir>` | Where to write the test (default: "ancha/tests") |
| `--force` | Replace an existing test with the same id |
| `--idempotency-key <key>` | Return the first result for a repeated request instead of drafting again |

## ancha test save

```bash theme={null}
ancha test save [options] <runId>
```

| Option | Description |
| - | - |
| `--name <name>` | Saved test name |

```bash theme={null}
ancha test save run_20261031-075305_58f8f7611bae17ed --name "Starter access"
```

```text Output theme={null}
Starter access: setup_b41cf0b5-ea57-446a-aef2-35b64ae190e7
Run again with ancha test run setup_b41cf0b5-ea57-446a-aef2-35b64ae190e7
```

## ancha test list and show

```bash theme={null}
ancha test list [options]
```

```text Output theme={null}
setup_b41cf0b5-ea57-446a-aef2-35b64ae190e7  Starter access  1 scenarios × 2 attempts
```

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

```text Output theme={null}
Starter access
ID: setup_b41cf0b5-ea57-446a-aef2-35b64ae190e7
Agent: Quickstart agent (agent:agent_2817abf5-f4bb-4cf3-9839-77309f18c2fc)
Scenarios: Discover the four local services
Attempts per scenario: 2
Parallel workers: 1
World seed: test-1
Inputs: pinned from run_20261031-075305_58f8f7611bae17ed
Run: ancha test run setup_b41cf0b5-ea57-446a-aef2-35b64ae190e7
```

## ancha test run

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

```text Output theme={null}
run_started runId=run_20261031-075317_ef7a7e5e915af358
run_20261031-075317_ef7a7e5e915af358: pass
Use ancha report or ancha explain to inspect the result.
```

Runs from clean worlds with your current agent code. If a scenario or its data changed since the test was saved, it refuses to start.

## ancha test remove

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

Deletes the saved setup and keeps its past runs.


## Related topics

- [Tests](https://docs.ancha.io/concepts/tests.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [ancha agent](https://docs.ancha.io/cli/agent.md)
- [Changelog](https://docs.ancha.io/changelog.md)
- [Test a Slack bot](https://docs.ancha.io/guides/test-a-slack-bot.md)


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