CLI overview

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.

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:

Output

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:

--server-url <url>
server.url in ancha.yaml
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 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:

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 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 for every error code.

Commands

Test loop

Command	What it does
`ancha init`	Write `ancha.yaml`, a starter scene for the tools your project uses, and instructions for coding agents.
`ancha doctor`	Check the setup and run the agent once.
`ancha run`	Run the agent against every scene, several times, and report the pass rate.
`ancha explain`	Show why trials failed: expected, actual and the calls behind each check.
`ancha report`	Print a finished run’s summary again, or write an HTML report.
`ancha baseline`	Freeze a run’s summary to compare later runs against.
`ancha status`	Show the state of a running or finished run.
`ancha wait`	Follow a run until it finishes.
`ancha logs`	Print a run’s events, and follow a detached run.
`ancha 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`	List the tools and the endpoints each one implements.
`ancha connect`	Print SDK settings for a tool.
`ancha scene`	Create, validate and preview scene files.
`ancha docs`	Print the documentation bundled with the CLI.

Automation

Command	What it does
`ancha schema`	Print the JSON Schema of `ancha.yaml`, scene files and the JSON outputs.
`ancha completion`	Print a shell completion script.

Worlds

Command	What it does
`ancha world up`, `ancha check`, `ancha world down`	Start a fresh world for your own harness, grade it, inspect it and remove it.
`ancha world gen`	Generate a world file from a description.
`ancha world`	Save versioned worlds of tools and starter data.

Servers and sandboxes

Command	What it does
`ancha serve`	Run an Ancha server.
`ancha env`	Create, list, reset and destroy environments from scene files.
`ancha sandbox`	Explore seeded tools by hand, without a scene.
`ancha mcp`	Serve a sandbox’s Slack to an MCP client.
`ancha ui`	Open the local console in your browser.

Hosted workspace

Command	What it does
`ancha login`	Sign in to your hosted workspace from this computer.
`ancha logout`	Forget the saved sign-in.
`ancha whoami`	Show which workspace commands use and where that choice came from.
`ancha secrets`	Set the variables, such as model keys, your agents get in the hosted workspace.

Agents and playgrounds

Command	What it does
`ancha agent`	Save an agent profile and run it against bundled scenarios.
`ancha playground`	Run tasks in fresh containers and inspect the attempts.
`ancha test`	Save and rerun agent runs with pinned inputs.
`ancha 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.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

CLI overview

Global options

Which server a command uses

Output

Exit codes

Commands

Test loop

Tools and scenes

Automation

Worlds

Servers and sandboxes

Hosted workspace

Agents and playgrounds

Files

​Global options

​Which server a command uses

​Output

​Exit codes

​Commands

​Test loop

​Tools and scenes

​Automation

​Worlds

​Servers and sandboxes

​Hosted workspace

​Agents and playgrounds

​Files

Global options

Which server a command uses

Output

Exit codes

Commands

Test loop

Tools and scenes

Automation

Worlds

Servers and sandboxes

Hosted workspace

Agents and playgrounds

Files