CLI Reference¶
The archetype CLI is built with Typer. Install via uv sync or pip install -e ..
The CLI is a thin HTTP client — every command (except serve) delegates to a running archetype serve instance.
Commands¶
archetype history¶
Show command history for a world.
archetype history <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--limit / -n |
integer | 50 |
Max commands to show |
archetype query¶
Query world state at a tick.
archetype query <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--tick / -t |
integer | — | Tick to query |
archetype run¶
Run simulation for N steps.
archetype run <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--steps / -n |
integer | 1 |
Number of steps |
archetype serve¶
Start the FastAPI server.
archetype serve [OPTIONS]
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--host |
text | 0.0.0.0 |
Bind host |
--port |
integer | 8000 |
Bind port |
--reload / --no-reload |
boolean | False |
Enable auto-reload |
archetype status¶
Show all worlds and their state.
archetype status
archetype step¶
Execute a single tick.
archetype step <WORLD_ID>
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
archetype world¶
World management commands
archetype world create¶
Create a new world.
archetype world create <NAME> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
NAME |
text | Yes | World name |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--uri |
text | ./archetype_data |
Storage URI |
--namespace |
text | archetypes |
Storage namespace |
archetype world fork¶
Fork a world (branch from current state).
archetype world fork <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | Source world ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--name / -n |
text | — | Name for the fork |
archetype world inspect¶
Show world details.
archetype world inspect <WORLD_ID>
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
archetype world list¶
List all worlds.
archetype world list
archetype world remove¶
Remove a world.
archetype world remove <WORLD_ID>
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |