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

> Save reusable, versioned worlds of tools and starter data for playground tests. Editing a world creates a revision; archiving keeps its history.

A saved world is a named set of tools with pinned starter datasets. Tests created with `ancha playground test create` use a world revision, and `ancha world up --world <id>` starts a live copy of one. See [Worlds](https://docs.ancha.io/concepts/worlds.md). Every subcommand takes `--json`.

Two other `ancha world` commands have their own pages: [`ancha world up`, `state`, `trace` and `down`](https://docs.ancha.io/cli/world-lifecycle) start and manage a live world for your own harness, and [`ancha world gen`](https://docs.ancha.io/cli/world-gen) generates a world file from a description.

## ancha world create

```bash theme={null}
ancha world create [options]
```

| Option | Description |
| - | - |
| `--name <name>` | World name |
| `--tools <names>` | Comma-separated tools |
| `--definition <file>` | Pinned sandbox configuration |

```bash theme={null}
ancha world create --name "Support workspace" --tools slack,github
```

```text Output theme={null}
world_eaf0fe5b-d5c4-4024-8a4d-4cbe9aa19b03 · Support workspace · revision 1
```

Use `--tools` for the starter datasets, or `--definition` with a configuration file from [`ancha sandbox configuration`](https://docs.ancha.io/cli/sandbox#ancha-sandbox-configuration).

## ancha world list

```bash theme={null}
ancha world list [options]
```

| Option | Description |
| - | - |
| `--include-archived` | Include archived worlds |

```text Output theme={null}
world_eaf0fe5b-d5c4-4024-8a4d-4cbe9aa19b03  Support workspace  1  slack, github
```

`list` shows saved worlds only, not the live worlds `ancha world up` starts.

## ancha world show

```bash theme={null}
ancha world show [options] <id>
```

| Option | Description |
| - | - |
| `--revision <number>` | Historical revision |

```text Output theme={null}
Support workspace · revision 1
slack   slack-starter   1.1.0
github  github-starter  1.1.0
```

## ancha world update

```bash theme={null}
ancha world update [options] <id>
```

| Option | Description |
| - | - |
| `--definition <file>` | World definition or patch |
| `--revision <number>` | Revision being edited |

Pass the current revision with `--revision`. An update creates a new revision; an edit based on an old revision is rejected. Existing tests keep their revision until you update them.

## ancha world archive

```bash theme={null}
ancha world archive [options] <id>
```

| Option | Description |
| - | - |
| `--revision <number>` | Revision being archived |

Hides the world from normal lists and keeps its history. `list --include-archived` shows it again.


## Related topics

- [Worlds](https://docs.ancha.io/concepts/worlds.md)
- [World lifecycle](https://docs.ancha.io/cli/world-lifecycle.md)
- [ancha world gen](https://docs.ancha.io/cli/world-gen.md)
- [ancha playground](https://docs.ancha.io/cli/playground.md)
- [ancha run](https://docs.ancha.io/cli/run.md)


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