> ## 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. # World lifecycle > Start a fresh world for your own harness with ancha world up, run your agent against its tools, grade it with ancha check, watch it with world state and world trace, and remove it with world down. `ancha run` starts your agent for you. When your own harness starts the agent, such as a test suite, an eval loop or a notebook, use the world lifecycle commands instead. `ancha world up` starts a fresh world and prints its tools' URLs and fake credentials. Your harness runs the agent with them. `ancha check` grades the world with the scene's checks and the same exit codes as `ancha run`. `ancha world down` removes the world. ```bash theme={null} ancha world up --scene scenes/support-reply/scene.yaml --json # envId, and env: the variables for your agent # start your agent with exactly the variables in env ancha check --env --json # exit 1 when a required check fails ancha world down --env ``` The agent gets the tools' variables, the task and the world's ID. It never gets the URL or token that controls the world. ## ancha world up ```bash theme={null} ancha world up [options] ``` | Option | Description | | - | - | | `--scene ` | Scene file to start (default: the one scene ancha.yaml names) | | `--test ` | Test file to start; same as --scene | | `--world ` | A saved world from ancha world list | | `--on ` | local (this computer) or cloud (your workspace); default: where ancha run would run | | `--seed ` | Seed for ids and data (default: "\:1") | | `--ttl ` | Remove the world after this long with no call from the agent and no ancha world or ancha check command on it (default: "30m") | Pass at most one of `--scene`, `--test` and `--world`. With none, `world up` starts the scene that `ancha.yaml` names, when it names exactly one. ```bash theme={null} ancha world up --scene scenes/starter/scene.yaml ``` ```text Output theme={null} running locally (worlds in a server on this computer, until ancha world down or 10 minutes without worlds) world b1p97rm9 is ready (scene starter); it expires at 2026-10-31T10:55:25.457Z unless used Give your agent these variables: SLACK_API_URL=http://127.0.0.1:56600/e/b1p97rm9/slack/api/ SLACK_BOT_TOKEN= SLACK_SIGNING_SECRET= SLACK_APP_TOKEN= GITHUB_API_URL=http://127.0.0.1:56600/e/b1p97rm9/github GITHUB_TOKEN= GITHUB_WEBHOOK_SECRET= ANCHA_ENV_ID=b1p97rm9 ANCHA_SCENE_ID=starter ANCHA_TASK="Discover resources through the declared native service APIs. ..." next: ancha check --env b1p97rm9 --json next: ancha world down --env b1p97rm9 ``` With `--json`, the result is one object: | Field | Meaning | | - | - | | `envId` | The world's ID. Pass it to `check`, `state`, `trace` and `down`. | | `workspace` | Where the world runs: `local:`, or the URL of the hosted world server. | | `sceneId` | The scene's `id`. Absent for a saved world. | | `services` | Each tool's URL and fake credentials, as objects. | | `env` | The variables to give the agent: the tools' variables, `ANCHA_ENV_ID`, and for a scene `ANCHA_SCENE_ID` and `ANCHA_TASK`. | | `expiresAt` | When the world is removed unless something uses it. | | `next` | The commands to run next. | Give the agent exactly the variables in `env`. See [Environment variables](https://docs.ancha.io/reference/environment-variables.md). `ancha schema world_up` prints the JSON Schema of this output. ### Where the world runs `world up` chooses a server the way `ancha run` does: `--server-url`, then `server.url` in `ancha.yaml`, then `ANCHA_SERVER_URL`, then the workspace saved by `ancha login`. With none of these it starts a server on this computer, which stays up until `ancha world down` removes the last world or ten minutes pass without one. The first line says which: ```text theme={null} running on hosted https://app.ancha.io/t/ (from ancha login; --local to run here) ``` `--on local` keeps the world on this computer whatever is configured. `--on cloud` puts it in your hosted workspace and exits `2` when no workspace is configured. A world in your workspace serves its tools at `https://app.ancha.io/t//e//`. Your agent runs wherever your harness runs it. See [Hosted workspace](https://docs.ancha.io/cloud/overview.md). ### The lease A world lives for `--ttl` after the last call from the agent or the last `ancha world` or `ancha check` command on it. The default is 30 minutes; the range is 1 second to 24 hours. Each of those renews the lease. After it expires, the world is gone and its commands fail with `ENV_NOT_FOUND`. ### Saved worlds `--world ` starts a world saved with [`ancha world create`](https://docs.ancha.io/cli/world): its tools and starter data, with no task and no checks. `ancha check` then needs `--test ` to know which checks to apply. ## ancha check ```bash theme={null} ancha check [options] ``` | Option | Description | | - | - | | `--env ` | World id from ancha world up | | `--test ` | Test or scene file whose checks to apply (default: the scene the world started from) | | `--scene ` | Same as --test | | `--check ` | A check to apply instead, as one JSON object (repeatable); each is required | `check` evaluates the checks against the world as it is now: the final state of the tools and every call the agent made. It does not end the world, so you can run it before and after the agent, or after each step. ```bash theme={null} ancha check --env b1p97rm9 ``` ```text Output theme={null} pass slack_access pass github_access verdict: pass (2 of 2 required checks pass) next: ancha world down --env b1p97rm9 ``` A failed check shows what was expected and what the world held: ```text Output theme={null} fail slack_access: expected agent calls * /api/*.*; got never called; agent made 0 call(s) fail github_access: expected agent calls * /*repos*; got never called; agent made 0 call(s) verdict: fail (0 of 2 required checks pass) next: ancha world trace --env b1p97rm9 --json next: ancha world down --env b1p97rm9 ``` The file's `pass` list decides which checks are required. A check outside it is evaluated, printed with `(not required)`, and does not change the verdict. Judge checks need `OPENROUTER_API_KEY` in the shell that runs `ancha check` and use `judge.model` from `ancha.yaml`. See [Checks](https://docs.ancha.io/concepts/checks.md). With `--json`: | Field | Meaning | | - | - | | `envId`, `workspace`, `sceneId` | The world, where it runs, and the scene whose checks applied. | | `verdict` | `pass` or `fail`. | | `checks` | Every result: `id`, `required`, `passed`, `status`, `expected`, `actual`, `explanation` and `evidence`. See [Checks reference](https://docs.ancha.io/reference/checks.md#results). | | `failures` | The required checks that failed: `check`, `expected`, `actual`, `explanation`. | | `next` | The commands to run next. | `ancha schema check` prints the schema. ## ancha world state ```bash theme={null} ancha world state --env ``` Prints the world's current state, tool by tool, as JSON: Slack's users, channels and messages, GitHub's repositories, issues and pull requests, and so on for every tool in the world. The text output is the same JSON. ## ancha world trace ```bash theme={null} ancha world trace [options] ``` | Option | Description | | - | - | | `--env ` | World id from ancha world up | | `--after ` | Only entries after this sequence number (default: "0") | ```text Output theme={null} 1 2026-10-21T14:00:00.858Z agent slack GET /api/conversations.list 200 2 2026-10-21T14:00:00.864Z agent github GET /repos/acme/starter 200 ``` Each line is the sequence number, the simulated time, who made the call (`agent`, or the world itself), the tool, the method and path, and the status. Before any call it prints `no calls yet`. With `--json`, each entry also carries the response body and `gap`, which is `true` for a call to an endpoint the replica does not implement. Poll with `--after ` to read only new entries. ## ancha world down ```bash theme={null} ancha world down --env ``` ```text Output theme={null} world b1p97rm9 removed ``` Removing a world that is already gone prints `world b1p97rm9 was already gone` and exits `0`. With `--json`, `removed` is `false`. ## Exit codes and errors | Code | When | | - | - | | `0` | `world up`, `state`, `trace` and `down` succeeded, or `check` passed. | | `1` | `check`: a required check failed. | | `2` | Usage: two of `--scene`, `--test` and `--world`; `--on` with a value other than `local` or `cloud`; `--on cloud` without a workspace; a `--ttl` outside 1s to 24h; `check` on a world that has no checks to apply; `check` with both `--test` and `--scene`. | | `3` | `ENV_NOT_FOUND`: the world expired, was removed, or its local server stopped. Start a new one with `ancha world up --json`. | Live worlds belong to the project directory you ran `world up` from, so run the other commands from the same directory. `ancha world list` lists saved worlds, not live ones. ## Related topics - [ancha run](https://docs.ancha.io/cli/run.md) - [For coding agents](https://docs.ancha.io/coding-agents.md) - [Attempts and runs](https://docs.ancha.io/concepts/attempts-and-runs.md) - [Changelog](https://docs.ancha.io/changelog.md) - [Environment variables](https://docs.ancha.io/reference/environment-variables.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.