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

> Validate ancha.yaml and every scene, then run the agent once against the first scene and confirm it reached each tool.

`ancha doctor` checks that a project is ready for `ancha run`. It validates the config and scenes, starts the tools, runs your agent once against the first scene and reports which tools the agent actually reached. It cleans up afterwards and does not change `latest`.

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

| Option | Description |
| - | - |
| `--agent <command>` | Override the configured agent command |
| `--no-agent` | Skip the agent trial and explicitly report incomplete agent verification |
| `--timeout <duration>` | Maximum diagnostic agent duration, at most 30s (default: "10s") |

## Example

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

```text Output theme={null}
pass  workspace: running locally (worlds in a server this command starts)
pass  node: Node 24.22.2; ancha 0.1.4
pass  config: Configuration is valid
pass  scenes: 1 scenes are valid
pass  runtime: Backend accepted every scene and released its diagnostic environments
pass  agent: Agent completed a bounded diagnostic trial (exited)
pass  native:slack: Observed a successful native slack API request from the configured agent
pass  native:github: Observed a successful native github API request from the configured agent
pass  native:datadog: Observed a successful native datadog API request from the configured agent
pass  native:pagerduty: Observed a successful native pagerduty API request from the configured agent
pass  business: Diagnostic scene checks passed
next: ancha run
```

## What it checks

| Check | Passes when |
| - | - |
| `workspace` | Says where the worlds run: locally, or on the hosted workspace you signed in to. See [CLI overview](https://docs.ancha.io/cli/overview.md#which-server-a-command-uses). |
| `node` | Node.js is version 24 or later. The line also names the installed CLI version. |
| `config` | `ancha.yaml` is valid. |
| `scenes` | Every scene file is valid. |
| `runtime` | The server accepts every scene. |
| `agent` | The agent ran and exited within the time limit (default `10s`, at most `30s`). |
| `native:<tool>` | The agent made at least one successful call to that tool. Server health and a clean exit do not count. |
| `business` | The first scene's checks passed. |

A tool the agent did not reach is a warning, not a failure, and so is a failed scene check. Each warning carries a hint:

```text Output theme={null}
warning  native:github: Successful native github API access was not observed
  configure the native SDK using ancha connect github; health and process exit do not prove agent access
warning  business: Diagnostic business checks failed; assess the agent separately from SDK connectivity
  ancha run --json, then ancha explain latest --json
next: ancha run
```

When the agent crashes or times out, `agent` fails and the output shows the end of its log.

## Exit codes

| Code | When |
| - | - |
| `0` | Every check passed, or only warnings remain. Also with `--no-agent` when the config, scenes and runtime are fine. |
| `2` | No agent command, an invalid config or scene, or a hosted server that rejected the API key. |
| `3` | The server or runtime failed, or the agent could not complete the diagnostic trial. |

`--json` prints `{"ok": true|false, "checks": [{"name", "status", "message", "hint"}], "next": [...]}`. `ok` is `false` only when a check failed.


## Related topics

- [Troubleshooting](https://docs.ancha.io/troubleshooting.md)
- [ancha.yaml](https://docs.ancha.io/reference/ancha-yaml.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [CLI overview](https://docs.ancha.io/cli/overview.md)
- [ancha login](https://docs.ancha.io/cli/login.md)


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