CLI (sapix)
Every administrative operation from the command line: status, chain verify, keys, peers, mutants, blobs, organisms, and JSON output for scripting.
What you'll learn
- ✓cargo install sapix-cli — build from source, or use pre-built binary
- ✓SAPIX_URL + SAPIX_API_KEY env vars for configuration
- ✓sapix status — record count, chain head, HLC, uptime
- ✓sapix chain verify <agent> --verbose — full cryptographic chain scan
- ✓sapix agents cage/uncage <id> — block/unblock writes before migrations
- ✓sapix agents export/import <id> — full strand archival and restore
- ✓sapix keys create <name> --scopes — create narrowly-scoped keys
- ✓sapix peers sync <peer_id> — force immediate replication after outage
- ✓All commands accept --json for machine-readable scripting output
Use sapix chain verify to confirm chain integrity on your orders agent. Export the strand to a JSONL file. Create a read-only key with strand:read,query:* scopes. Verify the key cannot write.
## CLI (sapix)
The sapix binary is the operator command-line interface for SapixDB. It exposes every administrative REST endpoint as a typed subcommand — no curl required.
Install
`bash
# From source (Rust toolchain required)
cargo install sapix-cli
# Or build from the monorepo
cargo build --release -p sapix-cli
cp target/release/sapix /usr/local/bin/
`
Configure
export SAPIX_URL=http://localhost:7475
export SAPIX_API_KEY=spx_key_...Or pass per-command: sapix --url http://... --key spx_key_... status
Subcommand reference
| Subcommand | Description |
|---|---|
sapix status | Agent state: record count, chain head, HLC, uptime |
sapix agents list | List all registered agents |
sapix agents status <id> | One agent: record count, cage state, zone |
sapix agents create <id> --zone <z> | Create (genesis) a new agent |
sapix agents cage <id> | Cage agent — blocks all writes, returns 423 |
sapix agents uncage <id> | Uncage agent — re-enables writes |
sapix agents records <id> | Stream recent strand records |
sapix agents export <id> | Export full strand to JSONL or .sapx file |
sapix agents import <id> | Import strand from export file |
sapix chain verify <id> | Full cryptographic chain scan |
sapix keys list | List all API keys |
sapix keys create <name> | Create a scoped API key |
sapix keys revoke <key_id> | Revoke a key |
sapix keys usage <key_id> | Request count, last used, rate limit hits |
sapix peers list | List replication peers |
sapix peers add <agent_id> <url> | Register a peer |
sapix peers remove <agent_id> | Remove a peer |
sapix peers sync <peer_id> | Trigger immediate push sync |
sapix mutant list | List schema proposals |
sapix mutant propose | Propose a schema change |
sapix mutant approve <id> | Approve a proposal |
sapix mutant reject <id> | Reject a proposal |
sapix mutant apply <id> | Apply an approved proposal |
sapix blobs put [--input <file>] | Upload blob from stdin or file |
sapix blobs get <hash> | Download blob |
sapix organisms list | List organisms |
sapix organisms status <id> | Members, agent statuses |
sapix organisms create <id> | Create an organism |
Common workflows
Verify chain integrity before a release:
`bash
sapix chain verify orders --verbose
# records_verified: 1204391
# chain_intact: true
`
Export strand for cold archival:
`bash
sapix agents export orders --output /backups/orders_2026-08-06.jsonl
`
Create a read-only CI key:
`bash
sapix keys create ci-read --scopes strand:read,query:*
`
Force peer sync after network outage:
`bash
sapix peers sync replica-eu-west-1
`
Cage an agent before a destructive migration:
`bash
sapix agents cage orders
# ... run migration ...
sapix agents uncage orders
`
JSON output
All subcommands accept --json for machine-readable output:
`bash
sapix status --json | jq '.record_count'
sapix keys list --json | jq '.[].name'
sapix agents list --json | jq '.[].agent_id'
`
---
Always keep SAPIX_API_KEY in a secrets manager — never expose it in CI logs. See also: Lesson 33 (API auth), Lesson 34 (scoped keys), Lesson 57 (Sherapd and Alabay watchdogs).