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

# ancha init

> 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 init` prepares the current directory for `ancha run`. It writes files only; it installs no dependencies, starts no agent and makes no network calls.

```bash theme={null}
ancha init [options]
```

| Option | Description |
| - | - |
| `--agent <command>` | The command that starts your agent (default: package.json scripts.start, a Procfile, pyproject.toml \[project.scripts] or the Dockerfile CMD) |
| `--template <template>` | Starter or incidents (default: "starter") |
| `--intent <description>` | Also generate a world (company, people, tool history) from this description and draft a first test with people for it (uses a model) |
| `--idempotency-key <key>` | With --intent: return the first world and test for a repeated request instead of generating again |

## Example

```bash theme={null}
ancha init
```

```text Output theme={null}
Created 7 files; updated 0; preserved 0.
agent: npm start (from package.json)
starter: Slack, GitHub
next: ancha run
```

Here `package.json` had a `start` script and depended on `@slack/web-api` and `@octokit/rest`, so the starter covers Slack and GitHub. The last line is the next command.

## The start command

Without `--agent`, `init` reads the first of these that names a command, and never runs anything:

| Source | Command it writes |
| - | - |
| `package.json` with a `scripts.start` | `npm start` |
| `Procfile` | The first process line's command |
| `pyproject.toml` with exactly one entry under `[project.scripts]` | That script's name |
| `Dockerfile` | The last `CMD` |

`--agent "<command>"` overrides them. When nothing names a command, `ancha.yaml` has no agent and the output ends with `next: set agent.command in ancha.yaml, then ancha run`.

## The tools it detects

`init` reads `package.json`, `requirements.txt`, `pyproject.toml` and `Pipfile` for known SDKs: `@slack/web-api`, `@slack/bolt`, `slack_sdk` and `slack-bolt` for Slack; `@octokit/rest`, `octokit` and `PyGithub` for GitHub; `@datadog/datadog-api-client` and `datadog-api-client` for Datadog; `@pagerduty/pdjs`, `pdpyras` and `pagerduty` for PagerDuty. The starter scene covers the tools it finds, so any agent that reaches each of them passes it. With no recognized SDK it covers all four, and the output says so. The detected language also sets the default for `ancha connect --lang`.

## Files it writes

| File | Contents |
| - | - |
| `ancha.yaml` | `agent.command`, `scenes: [scenes/**/scene.yaml]`, `trials: 1`, `parallel: 1`, `min_pass_rate: 1`. See [ancha.yaml](https://docs.ancha.io/reference/ancha-yaml.md). |
| `scenes/starter/scene.yaml` | The starter scene: the detected tools, a task that reads one thing from each, and one trace check per tool. |
| `scenes/starter/oracle.mjs` | A reference companion that makes the calls and passes. |
| `scenes/starter/null.mjs` | A reference companion that exits without calling anything, so the checks fail. |
| `.claude/skills/ancha/SKILL.md` | A Claude Code skill named `ancha` that teaches the run, explain, baseline and compare loop. |
| `AGENTS.md` | A managed section between `<!-- ancha:begin -->` and `<!-- ancha:end -->` with the same loop and rules. Other content in the file is kept. |
| `.gitignore` | `.ancha/`, which holds run history, traces and fake tokens. An existing file gets the line appended; one that already ignores `.ancha/` is left alone. |

Both instruction files tell a coding agent to run the CLI as `npx -y @ancha-labs/cli <command>` until it is installed, and as `ancha <command>` afterwards. See [For coding agents](https://docs.ancha.io/coding-agents.md).

Running `init` again keeps every existing file and reports it as preserved.

## The starter scene

The starter checks that your agent can reach each tool, with any HTTP method and a path only that tool serves. It is meant to be replaced with checks of real work.

| Check | Trace pattern |
| - | - |
| `slack_access` | `* /api/*.*` |
| `github_access` | `* /*repos*` |
| `datadog_access` | `* /api/v*/*` |
| `pagerduty_access` | `* /services*` |

The world is static and the time limit is 10 seconds. The reference companions show what passing and failing look like. Never configure them as the agent under test, and never show them to it.

## Incident scenes

`ancha init --template incidents` writes 31 files: the same instructions plus five living-world incident scenes under `scenes/incidents/`, each with reference companions, a shared fixtures folder and a README.

| Scene | Title | The agent should |
| - | - | - |
| `bad-deploy` | Orders requests are failing after a deploy | Restore healthy deployed content through a pull request and communicate verified recovery. |
| `db-disk-full` | Database writes are failing | Assign the open PagerDuty incident to the human database operator and communicate evidence, without changing code or claiming recovery. |
| `false-alarm` | Investigate the transient alert and current customer impact | Report findings to the incident room while leaving production and monitoring alone. |
| `flapping-monitor` | The telemetry monitor repeatedly pages while customer signals stay healthy | Add a downtime of at most 10 minutes, keep production unchanged and explain the impact. |
| `status-request` | Orders requests are failing after a deploy | Fix through a pull request and answer a human's status request in its thread. |

Each has a 10-minute time limit.

## JSON output

```json theme={null}
{"created":["ancha.yaml","scenes/starter/scene.yaml","scenes/starter/oracle.mjs","scenes/starter/null.mjs",".claude/skills/ancha/SKILL.md","AGENTS.md",".gitignore"],"skipped":[],"updated":[],"detection":{"language":"unknown","sdks":[],"evidence":[],"agent":"node agent.mjs","agentSource":"explicit"},"template":"starter","tools":["slack","github","datadog","pagerduty"],"next":["ancha run"]}
```

`detection.agentSource` is `explicit`, `package.json`, `Procfile`, `pyproject.toml`, `Dockerfile` or `unconfigured`. `updated` lists files `init` appended to, and `skipped` the files it preserved with the reason.

## Exit codes

`0` on success. `2` for an unknown template, an empty `--agent`, or an unsafe destination.


## Related topics

- [For coding agents](https://docs.ancha.io/coding-agents.md)
- [ancha.yaml](https://docs.ancha.io/reference/ancha-yaml.md)
- [Troubleshooting](https://docs.ancha.io/troubleshooting.md)
- [ancha connect](https://docs.ancha.io/cli/connect.md)
- [Quickstart](https://docs.ancha.io/quickstart.md)


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