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 episode¶
Run one episode.
archetype episode <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--max-steps / -n |
integer | 1000 |
Maximum episode steps |
--terminal-component |
text | — | Terminal component type name |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
--json |
boolean | False |
Emit raw JSON |
archetype history¶
Show audit 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 audit rows to show |
--actor-id |
text | — | Actor ID filter |
--idempotency-key |
text | — | Idempotency key |
--tick-from |
integer | — | Reserved for API v2 |
--tick-to |
integer | — | Reserved for API v2 |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
--json |
boolean | False |
Emit raw JSON |
archetype query¶
Query world state.
archetype query <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--types |
text | — | Comma-separated component types |
--tick / -t |
integer | — | Tick to query |
--ticks |
text | — | Comma-separated ticks; first is used |
--entity-ids |
text | — | Comma-separated entity IDs |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
--json |
boolean | False |
Emit raw JSON |
archetype rollout¶
Run a rollout from a base world.
archetype rollout <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--num-episodes / -e |
integer | 1 |
Number of episodes |
--max-steps / -n |
integer | 1000 |
Maximum steps per episode |
--terminal-component |
text | — | Terminal component type name |
--parallel |
boolean | False |
Run episodes concurrently |
--destroy-forks-on-complete |
boolean | False |
Destroy forked worlds after each episode; storage retained |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
--json |
boolean | False |
Emit raw JSON |
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 |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
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 [OPTIONS]
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
--json |
boolean | False |
Emit raw JSON |
archetype step¶
Execute a single tick.
archetype step <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
archetype entity¶
Entity mutation commands
archetype entity add-components¶
Add components to an entity.
archetype entity add-components <WORLD_ID> <ENTITY_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
ENTITY_ID |
integer | Yes | Entity ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--components |
text | — | JSON array of component payloads |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
archetype entity despawn¶
Despawn an entity.
archetype entity despawn <WORLD_ID> <ENTITY_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
ENTITY_ID |
integer | Yes | Entity ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
archetype entity remove-components¶
Remove component types from an entity.
archetype entity remove-components <WORLD_ID> <ENTITY_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
ENTITY_ID |
integer | Yes | Entity ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--types / --typ |
text | — | Comma-separated component type names |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
archetype entity spawn¶
Spawn an entity from component payloads.
archetype entity spawn <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--components |
text | — | JSON array of component payloads |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
archetype entity update¶
Overlay component values on an entity.
archetype entity update <WORLD_ID> <ENTITY_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
ENTITY_ID |
integer | Yes | Entity ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--components |
text | — | JSON array of component payloads |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
archetype hooks¶
Hook introspection commands
archetype hooks list¶
List deployment-configured hooks.
archetype hooks list <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
--json |
boolean | False |
Emit raw JSON |
archetype processors¶
Processor introspection commands
archetype processors list¶
List deployment-configured processors.
archetype processors list <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
--json |
boolean | False |
Emit raw JSON |
archetype resources¶
Resource introspection commands
archetype resources list¶
List deployment-configured resources.
archetype resources list <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
--json |
boolean | False |
Emit raw JSON |
archetype world¶
World management commands
archetype world create¶
Create a world. Defaults to API admin mode when auth is omitted.
archetype world create <NAME> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
NAME |
text | Yes | World name |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--storage / --uri |
text | ./archetype_data |
Storage URI |
--namespace |
text | archetypes |
Storage namespace |
--cache |
boolean | False |
Use default cache config |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
archetype world destroy¶
Drop the in-memory world. Storage and audit rows are retained.
archetype world destroy <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
archetype world fork¶
Fork a world.
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 |
--storage / --uri |
text | — | Storage URI |
--namespace |
text | archetypes |
Storage namespace |
--cache |
boolean | False |
Use default cache config |
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
archetype world inspect¶
Show world details.
archetype world inspect <WORLD_ID> [OPTIONS]
Arguments:
| Name | Type | Required | Description |
|---|---|---|---|
WORLD_ID |
text | Yes | World ID |
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
--json |
boolean | False |
Emit raw JSON |
archetype world list¶
List live worlds.
archetype world list [OPTIONS]
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--url |
text | — | Override ARCHETYPE_URL for this command |
--role / -r |
choice | — | Developer role shortcut; production callers should use --token |
--token |
text | — | Bearer token to send verbatim |
--json |
boolean | False |
Emit raw JSON |