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 chronicle¶
Chronicle — personal archive (local, no server required)
archetype chronicle ingest¶
Ingest chat histories, photos, and videos into a chronicle world.
Runs locally — does NOT require archetype serve.
Each source is attempted independently; missing sources are skipped.
archetype chronicle ingest [OPTIONS]
Options:
| Flag | Type | Default | Description |
|---|---|---|---|
--world-name |
text | chronicle |
World name for the chronicle |
--storage-uri |
text | ./archetype_data |
Storage URI |
--namespace |
text | chronicle |
Storage namespace |
--claude-code-dir |
text | — | Claude Code projects dir (default: ~/.claude/projects) |
--claude-ai-export |
text | — | Path to claude.ai data export (dir or conversations.json) |
--chatgpt-export |
text | — | Path to ChatGPT data export (dir or conversations.json) |
--apple-photos / --no-apple-photos |
boolean | False |
Ingest Apple Photos library (requires osxphotos + FDA) |
--apple-photos-dir |
text | — | Path to exported photos/videos folder (fallback) |
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 |