# Ancha

> Ancha runs your AI agent against stateful replicas of Slack, GitHub, Datadog and 35 other tools, grades each attempt with checks, and shows why it failed.

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

- [Introduction](https://docs.ancha.io/index.md): Test an AI agent against stateful replicas of Slack, GitHub, Datadog and 35 other tools, and check what it did.
- [Quickstart](https://docs.ancha.io/quickstart.md): Install the Ancha CLI, run a small agent against four replicated tools, break it, read why it failed and prove the fix.
- [For coding agents](https://docs.ancha.io/coding-agents.md): How a coding agent installs Ancha, runs an agent's tests with init, run and explain, reads JSON output and exit codes, proves a fix, and drives worlds from its own harness.
- [Test a Slack bot](https://docs.ancha.io/guides/test-a-slack-bot.md): Write a scene for a Slack support bot built on the official SDK, let Ancha catch a real bug in which thread it answers, read the evidence, and prove the fix.
- [How Ancha works](https://docs.ancha.io/concepts/overview.md): The objects Ancha uses (agent, tool, world, test, run, attempt and check) and how the CLI's scene and trial vocabulary maps onto them.
- [Worlds](https://docs.ancha.io/concepts/worlds.md): A world is the set of tools and starter data an attempt begins with. Every attempt gets its own copy, built from the same seed.
- [Tests](https://docs.ancha.io/concepts/tests.md): A test is a world plus tasks and how many times to try each one, saved so the same test runs again against new agent code.
- [Attempts and runs](https://docs.ancha.io/concepts/attempts-and-runs.md): A run tries every task of a test several times. Each attempt gets a fresh world and a fresh agent process, and Ancha records everything it did.
- [Checks](https://docs.ancha.io/concepts/checks.md): Checks decide whether an attempt passed. State checks read the final world, trace checks read the agent's API calls, process checks read what happened between the agent and the people in the world, and judge checks ask a model to grade text.
- [Tools](https://docs.ancha.io/tools/overview.md): The 38 tools Ancha replicates, which API version each one follows, how many endpoints it implements, and how your agent connects to it.
- [Slack](https://docs.ancha.io/tools/slack.md): A stateful replica of Slack's Web API for bot tokens: channels, direct messages, messages, threads, reactions and users, with Events API delivery and an MCP server.
- [Gmail](https://docs.ancha.io/tools/gmail.md): A stateful replica of the Gmail API v1: mailboxes, messages, threads, labels, drafts, attachments and history, where mail moves only between the mailboxes in the world.
- [Google Drive](https://docs.ancha.io/tools/google-drive.md): A stateful replica of the Google Drive API v3: files and folders in one My Drive, uploads and exports, permissions, comments, revisions and changes.
- [Microsoft Word](https://docs.ancha.io/tools/microsoft-word.md): A stateful replica of Microsoft Graph drive items for Word documents in one OneDrive: folders, .docx files built from paragraphs, versions, sharing links and invitations.
- [Notion](https://docs.ancha.io/tools/notion.md): A stateful replica of the Notion API: pages, blocks, databases and data sources, comments, users and search, as an internal integration sees them.
- [Dropbox](https://docs.ancha.io/tools/dropbox.md): A stateful replica of the Dropbox API v2 for one account: files and folders, uploads and downloads, search, revisions, shared links and shared folders.
- [Resend](https://docs.ancha.io/tools/resend.md): A stateful replica of Resend's REST API: transactional emails and batches, broadcasts, domains, contacts and segments, where mail is recorded rather than delivered.
- [GitHub](https://docs.ancha.io/tools/github.md): A stateful replica of GitHub's REST API: repositories, commits and Git data, file contents, pull requests and reviews, issues and labels, check runs, Actions runs and deployments.
- [Datadog](https://docs.ancha.io/tools/datadog.md): A stateful replica of Datadog's API v1 and v2: metric queries, log search, monitors and mutes, downtimes, dashboards, events and incidents.
- [PagerDuty](https://docs.ancha.io/tools/pagerduty.md): A stateful replica of PagerDuty's REST API v2 and Events API v2: users, services, escalation policies, schedules, on-call, incidents, notes and alert events.
- [Better Stack](https://docs.ancha.io/tools/better-stack.md): A stateful replica of Better Stack's Uptime API: monitors, heartbeats, incidents, on-call and status pages, where nothing is probed.
- [Linear](https://docs.ancha.io/tools/linear.md): A stateful replica of Linear's GraphQL API: issues, comments, labels, workflow states, teams, projects and users, pruned to the operations it serves.
- [Jira](https://docs.ancha.io/tools/jira.md): A stateful replica of Jira Cloud's REST API v3 and Agile API: projects, issues, JQL search, comments, transitions, links, watchers, users, boards and sprints.
- [Okta](https://docs.ancha.io/tools/okta.md): A stateful replica of Okta's Management API v1: users and their lifecycle, groups, applications and app assignments, and the System Log.
- [Amazon S3](https://docs.ancha.io/tools/amazon-s3.md): A stateful replica of the Amazon S3 REST API with SigV4: buckets, objects, tags, conditional writes, checksums and multipart uploads for one account.
- [Clerk](https://docs.ancha.io/tools/clerk.md): A stateful replica of Clerk's Backend API v1: users, organizations and memberships, invitations and sessions for one application instance.
- [HubSpot](https://docs.ancha.io/tools/hubspot.md): A stateful replica of HubSpot's CRM v3 API: companies, contacts and deals with search, batches, associations, pipelines and properties.
- [Salesforce](https://docs.ancha.io/tools/salesforce.md): A stateful replica of Salesforce's REST API v67.0: accounts, contacts, leads, opportunities, campaigns and campaign members, with SOQL queries and composite requests.
- [Attio](https://docs.ancha.io/tools/attio.md): A stateful replica of Attio's REST API v2: people, companies and deals with typed values and value history, lists and entries, notes, tasks and workspace members.
- [Gong](https://docs.ancha.io/tools/gong.md): A read-only replica of Gong's API v2: calls, extensive call data with CRM context, transcripts, users and workspaces.
- [Stripe](https://docs.ancha.io/tools/stripe.md): A stateful replica of the Stripe API in test mode: customers, products and prices, subscriptions, invoices and invoice items, payment intents, charges, refunds and the balance.
- [PayPal](https://docs.ancha.io/tools/paypal.md): A stateful replica of PayPal's REST APIs: checkout orders, authorizations, captures and refunds, catalog products, billing plans and subscriptions, and transaction reports.
- [Shopify](https://docs.ancha.io/tools/shopify.md): A stateful replica of the Shopify Admin GraphQL API: orders, products and variants, inventory, customers, fulfillments and refunds for one store.
- [Lob](https://docs.ancha.io/tools/lob.md): A stateful replica of Lob's Print & Mail API v1: addresses, letters, postcards and checks, bank accounts, templates and US address verification, where nothing is printed or mailed.
- [Google Analytics](https://docs.ancha.io/tools/google-analytics.md): A replica of the Google Analytics 4 Data API v1beta over REST: run reports, batch reports, metadata and compatibility checks over historical traffic.
- [Google Ads](https://docs.ancha.io/tools/google-ads.md): A stateful replica of the Google Ads API v26 over REST and gRPC: accounts, GAQL search, and mutations for budgets, search campaigns, ad groups, responsive search ads and keywords.
- [LinkedIn Ads](https://docs.ancha.io/tools/linkedin-ads.md): A stateful replica of LinkedIn's Marketing API version 202610: ad accounts, campaign groups, campaigns, creatives, targeting facets and campaign analytics.
- [ChatGPT Ads](https://docs.ancha.io/tools/chatgpt-ads.md): A stateful replica of the ChatGPT Ads Advertiser API v1: the ad account, campaigns, ad groups, ads with creative review, status changes and delivery insights.
- [Open-Meteo](https://docs.ancha.io/tools/open-meteo.md): A replica of Open-Meteo's forecast and geocoding API with a synthetic climate for ten seeded places. No API key.
- [Kalshi](https://docs.ancha.io/tools/kalshi.md): A stateful replica of Kalshi's Trade API v2: series, events and markets, order books, orders and fills, positions and settlements for one trading account.
- [CLI overview](https://docs.ancha.io/cli/overview.md): 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.
- [ancha init](https://docs.ancha.io/cli/init.md): Set up a project for Ancha: write ancha.yaml with the start command it finds, a starter scene for the tools your dependencies use, reference companions and instructions for coding agents. Installs and runs nothing.
- [ancha doctor](https://docs.ancha.io/cli/doctor.md): Validate ancha.yaml and every scene, then run the agent once against the first scene and confirm it reached each tool.
- [ancha run](https://docs.ancha.io/cli/run.md): Run the agent against every scene several times, each trial on a fresh copy of the tools, and report how often it passes. Compare with a baseline to prove a fix, and send the results to your workspace.
- [ancha explain](https://docs.ancha.io/cli/explain.md): Explain why trials of a finished run failed: crashes and timeouts with the end of the agent's log, expected versus actual and the API calls behind each failed check, coverage gaps, and what the agent's environment withheld.
- [ancha report](https://docs.ancha.io/cli/report.md): Print the summary of a finished run again, or write a self-contained offline HTML report into the run's directory.
- [ancha baseline](https://docs.ancha.io/cli/baseline.md): Freeze a completed run's summary under a name, so later runs can prove they did not get worse with ancha run --compare.
- [ancha status](https://docs.ancha.io/cli/status.md): Show the lifecycle state and progress of a foreground or detached ancha run.
- [ancha wait](https://docs.ancha.io/cli/wait.md): Follow a run until it finishes and exit with the run's own exit code. Stopping wait leaves the run running.
- [ancha logs](https://docs.ancha.io/cli/logs.md): Print a run's events, as text or NDJSON, and follow a detached run until it ends, exiting with the run's own exit code.
- [ancha runs](https://docs.ancha.io/cli/runs.md): Send a finished run to your workspace with ancha runs upload, and list, show and start the playground runs a workspace holds.
- [ancha twins](https://docs.ancha.io/cli/twins.md): List the tools Ancha replicates and show which endpoints each one implements, with notes on what it leaves out.
- [ancha connect](https://docs.ancha.io/cli/connect.md): Print the environment variables Ancha sets for a tool and an SDK snippet that points the official client at the replica. Makes no calls and installs nothing.
- [ancha scene](https://docs.ancha.io/cli/scene.md): Create scene files from templates, validate them, preview how a world changes over time, run reference companions, and print the scene JSON Schema.
- [ancha docs](https://docs.ancha.io/cli/docs.md): Print the documentation bundled with the installed CLI, by topic, for reading offline.
- [ancha schema](https://docs.ancha.io/cli/schema.md): Print the JSON Schema of ancha.yaml, scene files and the CLI's JSON outputs, for editor validation and for harnesses that parse Ancha's output.
- [ancha completion](https://docs.ancha.io/cli/completion.md): Print a shell completion script for zsh, bash or fish that completes ancha's command and subcommand names.
- [World lifecycle](https://docs.ancha.io/cli/world-lifecycle.md): 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 world gen](https://docs.ancha.io/cli/world-gen.md): Generate a world file from a one-paragraph description: a fictional company, its people and the history in its tools, written by a model into ancha/worlds/<id>.yaml.
- [ancha world](https://docs.ancha.io/cli/world.md): Save reusable, versioned worlds of tools and starter data for playground tests. Editing a world creates a revision; archiving keeps its history.
- [ancha serve](https://docs.ancha.io/cli/serve.md): Run an Ancha server in the foreground so environments, sandboxes and the local console can share it. Stops on Ctrl-C.
- [ancha env](https://docs.ancha.io/cli/env.md): Create, list, reset and destroy environments from scene files on a running Ancha server, to point an agent or a script at a scene's tools by hand.
- [ancha sandbox](https://docs.ancha.io/cli/sandbox.md): Start seeded tools without a scene or checks: pick tools or a preset, connect any client, inspect the records and the calls it made, fork fresh copies, and reset.
- [ancha mcp](https://docs.ancha.io/cli/mcp.md): Serve a sandbox's Slack to an MCP client over stdio, and print the mcpServers entry to add to your MCP host.
- [ancha ui](https://docs.ancha.io/cli/ui.md): Start the local Ancha console on a loopback port and print its URL. It reads the same .ancha workspace as the CLI.
- [ancha login](https://docs.ancha.io/cli/login.md): Sign in to your hosted Ancha workspace from this computer with a browser approval. Later commands run their worlds in the workspace.
- [ancha logout](https://docs.ancha.io/cli/logout.md): Forget the saved sign-in for a hosted Ancha workspace so commands use local servers again.
- [ancha whoami](https://docs.ancha.io/cli/whoami.md): Show which workspace or local server commands use, where that choice came from, where ancha run puts its worlds, and whether an API key is available. Never prints a key.
- [ancha secrets](https://docs.ancha.io/cli/secrets.md): Copy model provider keys and other variables from your shell into your hosted workspace, list their names, or remove them. Values never appear in arguments or output.
- [ancha agent](https://docs.ancha.io/cli/agent.md): Save a reusable agent profile (folder, start command, task input, execution and model provider), prepare and check it, and run it against bundled or workspace scenarios.
- [ancha playground](https://docs.ancha.io/cli/playground.md): Run tasks against a saved agent and world in fresh local containers, one per attempt, then inspect, compare, stop and rerun the attempts. Includes saved playground tests and multi-agent groups.
- [ancha test](https://docs.ancha.io/cli/test.md): 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 execution](https://docs.ancha.io/cli/execution.md): Check whether contained local execution is available, prepare the local container runtime for playground runs, and list Ancha's containers.
- [ancha.yaml](https://docs.ancha.io/reference/ancha-yaml.md): Every field of ancha.yaml, the config file for ancha run and ancha doctor: the agent and how it starts, which variables it inherits, scenes, trials, parallelism, pass rate, server and judge model.
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md): The scene file format ancha run uses: tools, starter data with refs, the simulated clock, the task, living-world rules, people and checks, field by field.
- [Checks reference](https://docs.ancha.io/reference/checks.md): Every field of state, trace, judge and process checks, with examples in YAML and JSON, and where each kind of check can be used.
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md): Every variable Ancha sets for your agent (tool URLs and fake credentials, task, trial and attempt variables, event feed endpoints), what the agent inherits from your shell, and every variable the ancha CLI reads.
- [Errors and exit codes](https://docs.ancha.io/reference/errors.md): Every error code the ancha CLI reports, the exit code it maps to, what usually causes it and what to do.
- [Hosted workspace](https://docs.ancha.io/cloud/overview.md): What you get when you sign in at app.ancha.io: a private machine with a console, a hosted world server and a container runtime, the private beta for running your own agent there, the monthly hours, and how to use it from the browser or the CLI.
- [Login and API keys](https://docs.ancha.io/cloud/login-and-api-keys.md): How the CLI and CI authenticate to your hosted workspace: ancha login on a computer, API keys from Settings for CI, where keys are stored, how to check them and how to revoke them.
- [Results in your workspace](https://docs.ancha.io/cloud/results.md): Send the results of runs on your computer to your hosted workspace with ancha run --upload or ancha runs upload, what the upload holds and redacts, and how the console shows and deletes them.
- [CI](https://docs.ancha.io/cloud/ci.md): Run your agent's Ancha tests in CI, fully local with no account or with the results sent to your hosted workspace with two secrets, and gate merges on the exit code.
- [Secrets](https://docs.ancha.io/cloud/secrets.md): Give agents that run in your hosted workspace the model provider keys they need, from your shell with ancha secrets, without pasting keys into a form or a file.
- [Troubleshooting](https://docs.ancha.io/troubleshooting.md): Fixes for common problems with Ancha 0.1.4: installing, connecting an agent to the tools, variables the agent did not get, checks that fail unexpectedly, timeouts, coverage gaps, comparisons, the hosted workspace, live worlds and playgrounds.
- [Changelog](https://docs.ancha.io/changelog.md): Releases of the Ancha CLI, @ancha-labs/cli on npm, with the user-facing changes in each.