> ## 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 gen > 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/.yaml. `ancha world gen` writes a world from a description. A model invents the company, its people and the history in each tool. Ancha turns the answer into a world file, validates it and writes it to `ancha/worlds/.yaml`. Runs read only that file, so you can edit it freely. ```bash theme={null} ancha world gen [options] ``` | Argument | Description | | - | - | | `description` | One paragraph about the company and the scenario | | Option | Description | | - | - | | `--id ` | World id (default: from the company and scenario) | | `--tools ` | Comma-separated tools: slack, github, pagerduty, hubspot (default: from the description) | | `--size ` | History size: s, m or l (default: "m") | | `--variants ` | Extra variants with the same people and new details (default: "0") | | `--from ` | Start from an existing world file | | `--out ` | Where to write the files (default: "ancha/worlds") | | `--force` | Overwrite existing files | | `--idempotency-key ` | Return the first result for a repeated request instead of generating again | ## Model key `world gen` calls a model through OpenRouter and spends credit. It needs `OPENROUTER_API_KEY` in the shell that runs it. Without the key it stops before writing anything: ```text Output theme={null} error[CONFIG_INVALID]: world gen needs a model key hint: set OPENROUTER_API_KEY, then run the same command again ``` A key the provider rejects, a key that is out of credit, or an overloaded provider also stop the command, each with a hint that says so. ## Example ```bash theme={null} export OPENROUTER_API_KEY=... # in your shell, not in a file ancha world gen "Acme sells warehouse analytics to manufacturers. A support bot answers customers in Slack and files bugs in GitHub. The Ridgeway Robotics pilot starts this week." --tools slack,github --size s ``` ```text Output theme={null} generating a world from the description (size s) company graph history (slack, github) people wrote ancha/worlds/acme-ridgeway-pilot.yaml tools: slack, github · people: erin, ben · 9 model calls · $0.0120 next: write a test with world: acme-ridgeway-pilot (ancha docs scenes) ``` The id, the people and the numbers depend on the description and the model's answers. The command prints one progress line per step, and a line for each answer it rejected and asked for again. ## What it writes | File | Contents | | - | - | | `ancha/worlds/.yaml` | The world: `version: 2`, `id`, `title`, `generated` (what wrote it, when, from which description, and the record's file name), `tools`, `start_time`, a `seed` for each tool, and `people`. The first line is a comment that says the file was generated and can be edited. | | `ancha/worlds/.gen.json` | The generation record: every model call with its step, prompt hash, tokens and cost, and the total `cost_usd`. Runs never read it. | | `ancha/worlds/-v1.yaml`, `-v2.yaml`, … | One file per variant from `--variants`: the same company and people, with new history and new fact details. | The seed holds what the description implies: Slack users and channels with threaded messages, GitHub repositories with files, commits, pull requests and labeled issues, PagerDuty users, policies and services, and HubSpot companies, contacts and deals. The people carry a goal, a style, facts they share when asked and decisions they make by rule. See [Test file](https://docs.ancha.io/reference/test-file.md) for every field. ## Sizes | `--size` | Slack messages per channel | GitHub issues | Pull requests | | - | - | - | - | | `s` | 5 | 5 | 1 | | `m` | 10 | 15 | 3 | | `l` | 18 | 30 | 6 | ## Tools `--tools` accepts `slack`, `github`, `pagerduty` and `hubspot`, and defaults to the tools the description implies. Any other tool exits `2`. To use one in the world, add its seed to the generated file by hand; `ancha sandbox configuration --tools --json` prints starter data to copy from. ## Using the world A world file holds everything a scene holds except the task and the checks. To run an agent against it, copy it to `scenes//scene.yaml`, remove `version` and `generated`, rename `tools` to `twins` and `rules` to `world_rules`, add `task` and `checks`, and validate it with `ancha scene validate`. Then run it with [`ancha run`](https://docs.ancha.io/cli/run) or start it with [`ancha world up --scene`](https://docs.ancha.io/cli/world-lifecycle). ## Repeating safely With `--idempotency-key `, running the same command again returns the first result instead of calling the model, as long as its files still exist. The text output then starts with `reused` and the JSON has `reused: true`. The same key with different arguments exits `2`: ```text Output theme={null} error[USAGE]: this --idempotency-key was used with different arguments hint: use a new key for a new request ``` `world gen` never overwrites a file unless you pass `--force`: ```text Output theme={null} error[USAGE]: ancha/worlds/acme-ridgeway-pilot.yaml already exists hint: pass --force to overwrite it, or --id ``` `--from ` starts from an existing world: its company, people and tools stay unless the description changes them. ## JSON output | Field | Meaning | | - | - | | `workspace` | `local:`. | | `id` | The world id. | | `world`, `record`, `variants` | Paths of the world file, the generation record and the variant files. | | `files` | Every path written. | | `tools`, `people` | The tools in the world and the refs of its people. | | `calls`, `cost_usd` | Model calls made and what they cost. | | `reused` | `true` when an idempotency key returned an earlier result. | | `next` | The commands to run next. | ## Exit codes `0` when the files are written or reused. `2` for a missing model key, an unknown tool, a `--size` other than `s`, `m` or `l`, `--variants` outside 0 to 10, an `--id` with characters other than lowercase letters, digits and hyphens, an existing file without `--force`, or an idempotency key reused with different arguments. ## Related topics - [ancha world](https://docs.ancha.io/cli/world.md) - [Troubleshooting](https://docs.ancha.io/troubleshooting.md) - [For coding agents](https://docs.ancha.io/coding-agents.md) - [CLI overview](https://docs.ancha.io/cli/overview.md) - [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.