> ## 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. # Changelog > Releases of the Ancha CLI, @ancha-labs/cli on npm, with the user-facing changes in each. Install or upgrade with `npm install -g @ancha-labs/cli@`. `ancha --version` prints the version you have. Entries without a version describe the hosted workspace at app.ancha.io, which changes without a CLI release. **0.1.4** November 1, 2026 ## @ancha-labs/cli 0.1.4 Tests drafted from one sentence, tests that name their world, and trace checks that count only calls that worked. ### Added * **`ancha test new ""`** drafts a test for the project's world: 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 uses your `OPENROUTER_API_KEY`, or your workspace's model credit when you're logged in. * **Tests that name their world.** A version 2 test names its world (`world: acme-support`, the file `ancha/worlds/acme-support.yaml`) or writes it inline. `ancha run`, `ancha world up --test`, `ancha check --test`, `ancha scene simulate` and `ancha doctor` read it. Its `deadline` is simulated time and its `timeout` the real time each attempt may take, whichever ends first. `ancha schema test` and `ancha schema world` print both formats. * **`ancha init --intent ""`** also generates a world from the description and drafts a first test with people for it. * **`ancha check --env --check ''`** applies check objects to a live world, for harnesses that ask what holds right now. * **`ancha twins seed `** prints a tool's seed fields, an example that validates as written, the checks and scripted events a scene can use on it, the variables the agent gets and its SDK settings. * **GitHub** repository collaborators and organization members, seeded with `repos[].collaborators`, and the state check `github.permission`. **Okta**: the state check `okta.user`. **PagerDuty** schedule overrides. **Google Drive** ownership transfer within the owner's domain. * **HubSpot webhooks** to the subscriptions in `hubspot.webhooks.subscriptions`, signed like HubSpot's (`X-HubSpot-Signature-v3`). Agents get `HUBSPOT_CLIENT_SECRET` to verify them. ### Changed * **`called` counts only calls that worked**: a status below 400, not a coverage gap, no Slack `ok: false` and no GraphQL answer with only `errors`. Add `status: any` to count every attempt. `not_called` still counts every attempt. * **The world plays out after the agent exits.** When a command agent exits on its own before the scene's last timed actor, the world runs to that actor, never past the timeout, before the checks are graded. People stop acting at the exit. * Google clients with a client-level `rootUrl` reach the replica: a call without `/e/{envId}/{service}` is routed by its bearer token. * When an agent crashes, the run summary quotes the end of its log. If the log names a variable your shell has but the agent didn't get, it names the `--pass-env` that passes it. The value is never printed. * Without `--json`, `ancha run` and `ancha logs` print one line per finished trial, and a run's first line says where the worlds run and what the agent can reach. * Scene, test and world files reject text that YAML cut at an unquoted ` #`, and name the line and the quoted fix. * `ancha init` recognizes the official clients of 24 tools and seeds every tool the project uses in the starter scene. `ancha agent detect` reads the current folder when `--cwd` is left out. **Hosted workspace** November 1, 2026 ## app.ancha.io * While the workspace machine sleeps, the console keeps its navigation and lists your worlds and agents as the machine last listed them, with the time. Opening one still starts the workspace. **0.1.3** October 31, 2026 ## @ancha-labs/cli 0.1.3 Eight tools, results in your workspace, and where a signed-in run puts its worlds. ### Added * **Eight tools.** Twilio, Google Calendar, Intercom, Zendesk, Asana, Discord, Sentry and Airtable (keys `twilio`, `google-calendar`, `intercom`, `zendesk`, `asana`, `discord`, `sentry` and `airtable`), 38 replicas in all. `ancha twins` lists them and `ancha twins coverage ` lists each one's endpoints. See [Tools](https://docs.ancha.io/tools/overview.md). * **Results in your workspace.** `ancha run --upload` (or `ANCHA_UPLOAD=1`) and `ancha runs upload ` send a finished run to your workspace, where the console shows it at `https://app.ancha.io/runs/` and **Delete run** removes it. The upload holds the summary, the inputs and each attempt's log (its last 4 MB), calls, final state, checks and explanations; the values of `--pass-env`, `--inherit-env` and `.ancha/openrouter.env` variables are redacted first. A failed upload is a warning unless `--upload-required`. The JSON `run_finished` event carries `upload`. In CI: `ANCHA_SERVER_URL` and `ANCHA_API_KEY` with `ancha run --local --upload`. See [Results in your workspace](https://docs.ancha.io/cloud/results.md). * **`ancha run --on local|docker|cloud`**: a process on this computer, the sealed container `ancha.yaml` describes (never a fallback to a process), or your workspace. `--on cloud` uploads this project, registers its agent (or updates it), connects it there and runs each test there as its own run, streaming the progress. Running your own agent in the workspace is in private beta. See [`ancha run`](https://docs.ancha.io/cli/run#where-the-agent-runs). * **`ancha runs list|show|start`** and `ancha attempt show`: the runs a workspace holds, with their grade and queue position; `runs start --agent --test ` runs one test with a saved agent, and in a hosted workspace its console runs it, so a dropped connection does not stop the run. See [`ancha runs`](https://docs.ancha.io/cli/runs). ### Changed * **A signed-in `ancha run` keeps its worlds on this computer**, as do `doctor`, `world up`, `env` and `sandbox`. The login names your workspace for `--upload`, `ancha secrets` and the commands that work on the workspace's agents, worlds, tests and runs. `--server-url`, `server.url`, `ANCHA_SERVER_URL` or `ancha world up --on cloud` put the worlds in the workspace. The first line of a signed-in run reads `running locally (worlds in a server this command starts; logged in to https://app.ancha.io/t/: --upload sends the results there)`, and `ancha whoami --json` reports `worlds`. See [CLI overview](https://docs.ancha.io/cli/overview.md#which-server-a-command-uses). * With a hosted workspace, `ancha agent` (except `agent detect`), `ancha world list|show|create|update|archive`, `ancha test` and `ancha runs` work on that workspace, the same agents, worlds, tests and runs the console shows, and every JSON object they print names its `workspace`. `--local` keeps a command on this project's `.ancha/`. `ancha agent add|update --cwd ` uploads the folder first: the files git tracks or would add, without `.anchaignore` patterns, hidden files, dependencies or credential-like files, at most 200 MB. **Hosted workspace** October 31, 2026 ## app.ancha.io * **Running your own agent in the workspace is in private beta.** **Bring your agent**, **Connect agent** and the `ancha agent` commands that reach the workspace are refused with `hosted runs of your own agent are in private beta for this workspace` until a workspace has access. **Settings** has a **Hosted runs** section with a request form. The sample agent and its runs, worlds, sandboxes, scenarios, tools, secrets and `ancha run` from your computer against hosted worlds are unchanged. See [Hosted workspace](https://docs.ancha.io/cloud/overview.md). * **Monthly hours.** A workspace has 10 hours of machine time a month, and **Settings** shows the hours used. When they are used up, the console shows a banner, the workspace keeps its data, and the machine can start again on the 1st. `ancha run` on your computer is not limited. * **The console is a view.** It opens while the workspace machine is asleep. The **Runs** page lists the runs the workspace ran, each at `https://app.ancha.io/runs/`. **Start workspace** starts the machine, as does a call to one of its worlds from the CLI; opening the console no longer does, and a new workspace gets its machine the first time you start it. **0.1.2** October 31, 2026 ## @ancha-labs/cli 0.1.2 Eighteen new tools, a world lifecycle for your own harness, generated worlds, people in the world with process checks, and fixes from a fresh-user test of 0.1.1 run the way a coding agent would. ### Added * **Eighteen tools.** Gmail, Google Drive, Microsoft Word, Notion, Dropbox, Resend, Better Stack, Linear, Jira, Okta, Amazon S3, Clerk, Attio, Stripe, PayPal, Shopify, Lob and Kalshi, thirty replicas in all. `ancha connect ` prints a snippet for every tool, including Open-Meteo. The Slack replica adds direct messages with the bot (`conversations.open`, 22 methods) and the GitHub replica adds labels (71 endpoints) and `issues` events. See [Tools](https://docs.ancha.io/tools/overview.md). * **Where the worlds run.** The first line of `ancha run`, `ancha doctor` and `ancha world up` says it, for example `running on hosted https://app.ancha.io/t/ (from ancha login; --local to run here)`, and run JSON carries `workspace` and `target`. `--local` keeps any command on this computer. `ancha whoami [--verify]` shows which workspace commands use and where that choice came from, and never prints a key. See [`ancha whoami`](https://docs.ancha.io/cli/whoami). * **World lifecycle.** `ancha world up` starts a fresh world for your own harness and prints its tools' URLs and fake credentials, `ancha check --env ` grades it with the same checks and exit codes as `ancha run`, and `ancha world state`, `trace` and `down` inspect and remove it. See [World lifecycle](https://docs.ancha.io/cli/world-lifecycle.md). * **Generated worlds.** `ancha world gen ""` writes a world file, with a company, its people and the history in its tools, to `ancha/worlds/.yaml`, plus its variants and a record of the generation. It calls a model and needs `OPENROUTER_API_KEY`; `--idempotency-key` makes a retry reuse the first result. See [`ancha world gen`](https://docs.ancha.io/cli/world-gen). * **People and process checks.** A scene can hold people who answer the agent through the tools, hold facts until asked and decide by rule. The checks `revealed`, `knows`, `told`, `decided`, `message`, `never`, `before` and `within` read what the engine recorded. New: the `github.issue` state check, the `issue_labeled` predicate, `when` on a person's fact, `starts_when` on a fault, labels and authors in GitHub seeds, and `agent.input: per_event` for agents that wait for people. See [Checks reference](https://docs.ancha.io/reference/checks.md) and [Test file](https://docs.ancha.io/reference/test-file.md#people). * **For scripts and coding agents.** `ancha schema [kind]` prints the JSON Schema of `ancha.yaml`, scene files and the `run_started`, `run_finished`, `explain`, `world_up`, `check` and error outputs. `ancha run --idempotency-key ` makes a retry return the original run. `ancha logs --follow` streams a run's events and exits with its exit code. `ancha completion bash|zsh|fish` prints a completion script. `ANCHA_JSON=1` acts as `--json` everywhere. `ancha --help` is one page and `ancha advanced` lists the rest. `ancha` alone prints where to start, and `ancha run` without `ancha.yaml` says to run `ancha init`. * **`ancha init`** takes the start command from `package.json`, a Procfile, `pyproject.toml` or the Dockerfile, writes a starter scene for the tools your dependencies use, writes only the `.mjs` reference companions, adds `.ancha/` to `.gitignore`, and ends with `next: ancha run`. `ancha run`, `ancha explain` and `ancha doctor` end with `next: ` and carry `next` in JSON. See [`ancha init`](https://docs.ancha.io/cli/init). * **Per-check comparison.** `ancha run --compare` compares every required check: a check whose pass rate falls regresses the run (exit 1) even when the scene's rate holds, and `comparison.droppedChecks` lists it first. `ancha doctor` shows the end of a failing agent's output and the CLI's own version. `ancha explain` lists coverage gaps without `--strict`. * Agent names are unique per workspace: adding the same agent again returns it, and a different agent with the same name is refused. Container execution (`agent.execution`) is documented in `ancha docs run`. ### Changed * **The agent's environment.** `ancha run`, `ancha doctor` and `ancha scene simulate` no longer hand a local agent your whole shell. It gets a base set (`PATH`, `HOME`, locale, CA files, `TMPDIR`, virtual-environment paths), Ancha's variables and the tools' variables. Name anything else in `agent.pass_env` in `ancha.yaml` or with `--pass-env NAME`. `--inherit-env` restores the old behavior and prints a warning. The run summary says what the agent got. See [`ancha run`](https://docs.ancha.io/cli/run#what-the-agent-gets). * Agents no longer receive `ANCHA_WORLD_SEED`, and `{{world.seed}}` is gone from `agent.env` templates. * A hosted server that rejects or needs the API key gives `AUTH_INVALID` (exit 2) with a hint to run `ancha login`, instead of `SERVER_UNREACHABLE` (exit 3). See [Errors](https://docs.ancha.io/reference/errors.md). * `ancha doctor` exits 0 when only warnings remain; `ok` is false only when a check failed. * `ancha docs` lists its topics first, `--json` includes `topics`, and there is a new `cloud` topic. The bundled docs are written for installed users. * **Starter data 1.1.0.** The fictional company is Acme, its customer Ridgeway Robotics, and its repositories `acme/orders`, `acme/web` and `acme/warehouse-sync`; 0.1.1 called them Northstar Analytics, Acme Robotics and `northstar/orders`. Refs such as `$slack_support` and `$github_orders` are unchanged. Every tool has more history, and Open-Meteo has ten places. See [Worlds](https://docs.ancha.io/concepts/worlds.md#starter-data). * The local playground tool image is tagged per installed runtime (`ancha-world:`), so projects on different versions never overwrite each other's image. Run `ancha execution prepare` once after upgrading; `ancha execution doctor --json` reports `worldImage` and `worldImageReady`. ### Fixed * The starter scene's checks accept any HTTP method (`* /api/*.*` for Slack): the official Slack SDK POSTs. The shipped examples use `*` for Slack methods too. * `/_ancha/health` reports the installed version instead of `0.0.0`. * Piping a command into a reader that stops early (`ancha run | head -1`) no longer crashes with an EPIPE stack trace: the command finishes, cleans up and exits with its own code. * An agent run in a container no longer finds `ancha.yaml`, `ancha/`, scene folders or the run's scene files in its `/workspace`, so it cannot read the checks it is graded by. `agent.execution.files` cannot select them either. * No hint or document tells you to run a package manager other than npm, and the npm page is a user README. * A missing or mismatched native SQLite binary (an install whose scripts npm skipped) stops with the exact reinstall command instead of a list of paths. * The skill that `ancha init` writes and the one the console's Help page downloads are the same file. **0.1.1** October 31, 2026 ## @ancha-labs/cli 0.1.1 * **Open-Meteo.** A twelfth tool: weather forecasts and place search for six seeded places, with no API key. See [Open-Meteo](https://docs.ancha.io/tools/open-meteo.md). * **Graded playground tasks.** Playground task files accept `state` and `trace` checks, up to 20 per task. Attempts with checks are graded passed or failed; tasks without checks stay ungraded. See [`ancha playground`](https://docs.ancha.io/cli/playground). * **One cast across the starter data.** Every tool's starter data now uses the same Northstar Analytics people and records as the hosted workspace: Ben Carter, Rachel Moore and Mike Turner at Northstar, and Erin Walsh at Acme Robotics. See [Worlds](https://docs.ancha.io/concepts/worlds.md#starter-data). * **Starter scene works with hosted worlds.** The starter scene's reference companion accepts tool URLs from a hosted world server, so the starter runs after `ancha login` as well as locally. Commands and flags are unchanged from 0.1.0. **0.1.0** October 30, 2026 ## @ancha-labs/cli 0.1.0 The first public release on npm. * **Eleven tools:** Slack, GitHub, Datadog, PagerDuty, HubSpot, Salesforce, Gong, Google Analytics, Google Ads, LinkedIn Ads and ChatGPT Ads, each a stateful replica of a documented API subset with fictional starter data. * **The test loop:** `ancha init`, `doctor`, `run`, `explain`, `report` and `baseline`, with `run --compare` to prove a fix and `run --detach` with `status` and `wait` for long runs. * **Checks:** state checks for Slack, GitHub, Datadog and PagerDuty, trace checks for every tool, and model-graded judge checks. * **Hosted workspace from the CLI:** `ancha login`, `logout` and `secrets`, and runs against hosted worlds with `ANCHA_SERVER_URL` and `ANCHA_API_KEY`. * **Exploring and integrating:** sandboxes, environments, a Slack MCP server, `ancha connect` SDK snippets and the local console. * **Agents and playgrounds:** saved agent profiles, versioned worlds, and container playground runs with saved tests. * **For automation:** `--json` on every command and stable exit codes from `0` to `4`. ## Related topics - [Jira](https://docs.ancha.io/tools/jira.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.