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

> Create scene files from templates, validate them, preview how a world changes over time, run reference companions, and print the scene JSON Schema.

`ancha scene` works with scene files, the YAML files `ancha run` uses. See [Test file](https://docs.ancha.io/reference/test-file.md) for the format.

## ancha scene new

```bash theme={null}
ancha scene new [options] <id>
```

| Argument | Description |
| - | - |
| `id` | Lowercase scene id: letters, digits and hyphens |

| Option | Description |
| - | - |
| `--twins <twins>` | Comma-separated twins: slack,github,datadog,pagerduty |

```bash theme={null}
ancha scene new support-reply --twins slack,github
```

```text Output theme={null}
Created scenes/support-reply/scene.yaml and oracle/null companions. Validate: ancha scene validate scenes/support-reply/scene.yaml
```

It writes `scene.yaml`, `tasks.json` and the reference companions `oracle.mjs`, `oracle.ts`, `null.mjs` and `null.ts` into `scenes/<id>/`. The scene starts as an access check, like the starter: a minimal seed for each tool and one trace check per tool. Replace the task and checks with your own. The ID must be lowercase letters, digits and hyphens. An existing destination is rejected. `--twins` accepts `slack`, `github`, `datadog` and `pagerduty`.

## ancha scene validate

```bash theme={null}
ancha scene validate [options] <files...>
```

| Argument | Description |
| - | - |
| `files` | Scene YAML files |

```bash theme={null}
ancha scene validate scenes/starter/scene.yaml
```

```text Output theme={null}
ok  scenes/starter/scene.yaml (starter)
```

Invalid files exit `2` and list every problem with its path:

```text Output theme={null}
error[SCENE_INVALID]: id: must match [a-z0-9-]+ (lowercase letters, digits and hyphens)
  start_time: expected an ISO 8601 timestamp with a timezone, e.g. 2026-03-04T14:00:00Z
```

## ancha scene simulate

```bash theme={null}
ancha scene simulate [options] <scene>
```

| Argument | Description |
| - | - |
| `scene` | Scene YAML file (companions are sibling oracle.ts/null.ts) |

| Option | Description |
| - | - |
| `--until <duration>` | Relative world preview horizon, 0 to 24h (default: scene timeout); conflicts with companions |
| `--seed <seed>` | Seed for ids and randomness |
| `--oracle` | Run sibling oracle.ts with the ordinary scene timeout and trial exits |
| `--null` | Run sibling null.ts with the ordinary scene timeout (expected exit 1) |

Without a companion flag, `simulate` runs the world with no agent up to `--until` (default: the scene's timeout) and shows how the checks stand. Use it to see what a living world does on its own. A preview exits `0` even when checks fail:

```text Output theme={null}
World preview: starter at 10000ms (valid; checks failed)
A world preview does not run an agent trial; unresolved outcome checks do not make the preview invalid.
fail slack_access: The agent never made a call matching "GET /api/conversations.list". ...
```

`--oracle` runs the scene's `oracle` companion as the agent, which should pass. `--null` runs the `null` companion, which should exit cleanly and fail the checks (exit `1`). Together they show that the checks can tell a good response from a useless one. A `.mjs` companion is preferred over a `.ts` one with the same name.

## ancha scene schema

```bash theme={null}
ancha scene schema [options]
```

```bash theme={null}
ancha scene schema > scene.schema.json
```

Prints the JSON Schema of scene files, always as JSON. Point your editor's YAML language server at it for completion and validation.

## Exit codes

`0` on success. `1` when a companion's checks fail. `2` for invalid scenes or usage. `3` for infrastructure failures. `4` for coverage gaps in a companion run.


## Related topics

- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [ancha.yaml](https://docs.ancha.io/reference/ancha-yaml.md)
- [ancha world gen](https://docs.ancha.io/cli/world-gen.md)
- [ancha schema](https://docs.ancha.io/cli/schema.md)
- [World lifecycle](https://docs.ancha.io/cli/world-lifecycle.md)


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