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

# CLI overview

> How the ancha CLI is organized, its global options, how it picks a server, its output formats and exit codes, and an index of every command in 0.1.4.

The `ancha` CLI is published on npm as `@ancha-labs/cli`. This reference covers version 0.1.4. It needs Node.js 24 or later.

```bash theme={null}
npm install -g @ancha-labs/cli   # then run: ancha <command>
npx -y @ancha-labs/cli@0.1.4 <command>   # without installing
```

`ancha` without a command prints where to start and exits `2`:

```text Output theme={null}
Ancha: simulation playgrounds for agents. Start here:
  ancha init       set up this project: ancha.yaml, a starter scene, coding-agent instructions
  ancha run        run your agent against fresh worlds and grade it
  ancha explain latest   why it failed: each check, expected vs actual, the calls behind it
  ancha login      use your hosted workspace at app.ancha.io (one browser approval)
  ancha docs       the guide, offline
  ancha --help     every command
```

## Global options

These work with every command.

| Option | Description |
| - | - |
| `--json` | Machine-readable output on stdout: one JSON object, or NDJSON events for `run`, `wait` and `logs`. |
| `--config <path>` | Config file. Default: `ancha.yaml` in the current directory. |
| `--server-url <url>` | The Ancha server to use. See below. |
| `--local` | Use a server on this computer, ignoring the saved login, `ANCHA_SERVER_URL` and `server.url`. |
| `-V, --version` | Print the version, `0.1.4`. |
| `-h, --help` | Print help for a command. |

Setting `ANCHA_JSON=1` in the environment acts as `--json` on every command.

`ancha --help` fits on one page. `ancha advanced` lists the commands it leaves out: `agent`, `serve`, `ui`, `scene`, `env`, `sandbox`, `mcp`, `execution`, `playground`, `status`, `wait`, `logs`, `report`, `check`, `runs` and `attempt`. `ancha --help --json` prints every command and flag as one JSON tree, and `ancha <command> -h` prints one command's flags.

## Which server a command uses

Commands that create worlds choose a server in this order:

1. `--server-url <url>`
2. `server.url` in `ancha.yaml`
3. The `ANCHA_SERVER_URL` environment variable

`--local` skips all three. With none of these, `ancha run`, `ancha doctor` and `ancha world up` start a private server on this computer for the duration of the command, also when you are signed in. Other server commands, such as `ancha env` and `ancha sandbox`, use `http://127.0.0.1:4400`, where `ancha serve` listens by default.

The workspace saved by `ancha login` does not move the worlds. It names the workspace that `ancha run --upload` sends results to, that `ancha run --on cloud` runs in, and that `ancha secrets`, `ancha agent`, `ancha world create|list|show|update|archive`, `ancha test` and `ancha runs` work on. [`ancha whoami`](https://docs.ancha.io/cli/whoami) shows the workspace, where that choice came from, and where `ancha run` puts its worlds. `ancha logout` forgets the saved workspace.

The first line of `ancha run`, `ancha doctor` and `ancha world up` says where the worlds run:

```text theme={null}
running locally (worlds in a server this command starts)
running locally (worlds in a server this command starts; logged in to https://app.ancha.io/t/<workspace>: --upload sends the results there)
running on hosted https://app.ancha.io/t/<workspace> (from ANCHA_SERVER_URL; --local to run here)
```

## Output

* Human output goes to stdout. Errors go to stderr as `error[CODE]: message` with a `hint:` line that names the next command. Most commands end with a `next:` line.
* With `--json`, results and errors both go to stdout. An error is `{"error": {"code": "...", "message": "...", "hint": "..."}}`.
* Commands never prompt. Every input comes from flags, files or the environment.
* [`ancha schema`](https://docs.ancha.io/cli/schema) prints the JSON Schema of `ancha.yaml`, scene files and every JSON output.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success. For `run`: every required check passed and nothing regressed. |
| `1` | A check failed, the pass rate was too low, or a comparison regressed. |
| `2` | Usage, config, scene or authentication error. |
| `3` | Infrastructure error, or a trial Ancha could not run correctly. |
| `4` | `run --strict` only: the agent called an endpoint a replica does not implement. |

See [Errors](https://docs.ancha.io/reference/errors.md) for every error code.

## Commands

### Test loop

| Command | What it does |
| - | - |
| [`ancha init`](https://docs.ancha.io/cli/init) | Write `ancha.yaml`, a starter scene for the tools your project uses, and instructions for coding agents. |
| [`ancha doctor`](https://docs.ancha.io/cli/doctor) | Check the setup and run the agent once. |
| [`ancha run`](https://docs.ancha.io/cli/run) | Run the agent against every scene, several times, and report the pass rate. |
| [`ancha explain`](https://docs.ancha.io/cli/explain) | Show why trials failed: expected, actual and the calls behind each check. |
| [`ancha report`](https://docs.ancha.io/cli/report) | Print a finished run's summary again, or write an HTML report. |
| [`ancha baseline`](https://docs.ancha.io/cli/baseline) | Freeze a run's summary to compare later runs against. |
| [`ancha status`](https://docs.ancha.io/cli/status) | Show the state of a running or finished run. |
| [`ancha wait`](https://docs.ancha.io/cli/wait) | Follow a run until it finishes. |
| [`ancha logs`](https://docs.ancha.io/cli/logs) | Print a run's events, and follow a detached run. |
| [`ancha runs`](https://docs.ancha.io/cli/runs) | Send a finished run to your workspace, and list, show and start the runs a workspace holds. |

### Tools and scenes

| Command | What it does |
| - | - |
| [`ancha twins`](https://docs.ancha.io/cli/twins) | List the tools and the endpoints each one implements. |
| [`ancha connect`](https://docs.ancha.io/cli/connect) | Print SDK settings for a tool. |
| [`ancha scene`](https://docs.ancha.io/cli/scene) | Create, validate and preview scene files. |
| [`ancha docs`](https://docs.ancha.io/cli/docs) | Print the documentation bundled with the CLI. |

### Automation

| Command | What it does |
| - | - |
| [`ancha schema`](https://docs.ancha.io/cli/schema) | Print the JSON Schema of `ancha.yaml`, scene files and the JSON outputs. |
| [`ancha completion`](https://docs.ancha.io/cli/completion) | Print a shell completion script. |

### Worlds

| Command | What it does |
| - | - |
| [`ancha world up`, `ancha check`, `ancha world down`](https://docs.ancha.io/cli/world-lifecycle) | Start a fresh world for your own harness, grade it, inspect it and remove it. |
| [`ancha world gen`](https://docs.ancha.io/cli/world-gen) | Generate a world file from a description. |
| [`ancha world`](https://docs.ancha.io/cli/world) | Save versioned worlds of tools and starter data. |

### Servers and sandboxes

| Command | What it does |
| - | - |
| [`ancha serve`](https://docs.ancha.io/cli/serve) | Run an Ancha server. |
| [`ancha env`](https://docs.ancha.io/cli/env) | Create, list, reset and destroy environments from scene files. |
| [`ancha sandbox`](https://docs.ancha.io/cli/sandbox) | Explore seeded tools by hand, without a scene. |
| [`ancha mcp`](https://docs.ancha.io/cli/mcp) | Serve a sandbox's Slack to an MCP client. |
| [`ancha ui`](https://docs.ancha.io/cli/ui) | Open the local console in your browser. |

### Hosted workspace

| Command | What it does |
| - | - |
| [`ancha login`](https://docs.ancha.io/cli/login) | Sign in to your hosted workspace from this computer. |
| [`ancha logout`](https://docs.ancha.io/cli/logout) | Forget the saved sign-in. |
| [`ancha whoami`](https://docs.ancha.io/cli/whoami) | Show which workspace commands use and where that choice came from. |
| [`ancha secrets`](https://docs.ancha.io/cli/secrets) | Set the variables, such as model keys, your agents get in the hosted workspace. |

### Agents and playgrounds

| Command | What it does |
| - | - |
| [`ancha agent`](https://docs.ancha.io/cli/agent) | Save an agent profile and run it against bundled scenarios. |
| [`ancha playground`](https://docs.ancha.io/cli/playground) | Run tasks in fresh containers and inspect the attempts. |
| [`ancha test`](https://docs.ancha.io/cli/test) | Save and rerun agent runs with pinned inputs. |
| [`ancha execution`](https://docs.ancha.io/cli/execution) | Check and prepare the local container runtime. |

## Files

Commands keep their state in `.ancha/` in the current directory: `runs/` for `ancha run` results, `baselines/` for baselines, `playgrounds/` for agents, worlds, tests and playground runs, and the records of idempotency keys and live worlds. Run every command from the same directory to share them. `ancha init` adds `.ancha/` to `.gitignore`.


## Related topics

- [ancha whoami](https://docs.ancha.io/cli/whoami.md)
- [ancha doctor](https://docs.ancha.io/cli/doctor.md)
- [ancha run](https://docs.ancha.io/cli/run.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [Attempts and runs](https://docs.ancha.io/concepts/attempts-and-runs.md)


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