CLI reference
Every snug command group, with its subcommands and the examples the binary
itself ships. Run snug <command> --help for the same information at the
terminal, and snug <command> <subcommand> --help for a subcommand's options.
These apply to every command.
| Option | Environment | Default | What it does |
|---|
-u, --api-url <URL> | SNUG_API_URL | http://localhost:4000 | Which deployment to talk to |
-t, --token <TOKEN> | SNUG_API_TOKEN | | The credential to send |
--output <FORMAT> | | table | table, json, or compact |
-q, --quiet | | | Suppress output; errors still print |
-v, --verbose | | | Explain what the command is doing |
--no-color | | | Plain text, no ANSI colour |
--timeout <SECONDS> | | 30 | Per-request timeout |
-V, --version | | | Print the version and exit |
Token signing commands also read JWT_PRIVATE_KEY and JWT_PUBLIC_KEY.
--output json prints the bare payload with the transport envelope removed, so
fields are addressed directly - jq '.key', never jq '.data.key'. Progress
and success notices go to stderr in that mode, leaving stdout clean to pipe.
A command exits non-zero when the operation fails, and prints a parseable error
body on stdout in JSON mode. See Getting started
for the full contract.
| Command | What it does |
|---|
auth | Authentication and user management |
scim | SCIM 2.0 provisioning |
admin | Admin operations |
jwt | JWT token generation and management |
health | Check API health |
metrics | Show Prometheus metrics |
openapi | OpenAPI specification export |
config | Configuration management |
rate-limit | Rate limit administration (tiers, modules, endpoints, users, self-serve limits) |
circuit-breaker | Distributed circuit breaker management |
| Command | What it does |
|---|
kv | Key-value store operations |
blobs | Blob storage operations |
distributed-state | Distributed state and locking operations |
ecs | Entity Component System operations |
i18n | Localization and translation management |
live-json | Live JSON real-time database operations |
remote-config | Remote configuration management |
vault | Time-Locked Attestation Vault: seal, reveal, witness, and lottery |
lineage | Breeding and trait inheritance |
| Command | What it does |
|---|
pubsub | Pub/Sub operations |
websocket | WebSocket admin operations (stats, cleanup) |
mq | Message Queue - SNS/SQS-style topics, queues, and subscriptions |
queues | Manage queues |
inbox | Inbox persistent notifications |
presence | Presence occupancy and cognitive-state operations |
comment | Universal threaded comments with moderation and reactions |
timeline | Timeline Service - Time-series event storage |
webhooks | Webhook management |
| Command | What it does |
|---|
jobs | Manage jobs (schedule, cancel, list) |
job-queues | Manage job queue manifests (create, update, pause, resume, delete) |
fsm | Finite State Machine operations |
chrono | Temporal resource regeneration, cooldowns and idle accrual |
director | Director - Tension-curve pacing engine |
consensus | Consensus-based truth registry with reputation-weighted BFT voting |
hitl | HITL - human-in-the-loop approval requests and decisions |
lease | Lease exclusive, time-bound access to unique resources |
arbiter | Arbiter LLM-as-a-judge reasoning and evaluation |
| Command | What it does |
|---|
treasury | Treasury virtual economy: wallets, transfers, holds, and analytics |
meter | Meter - Usage metering, quotas, and billing rollups |
cart | Cart and checkout-intent operations |
item | Item Engine: inventory, crafting, durability, and collections |
auctions | Auction management |
promo-code | Promo code generation, redemption, and entitlement locks |
subscription | Subscription entitlement timing management |
surge-pricing | Surge Pricing - Dynamic pricing policies and calculations |
loyalty | Loyalty and rewards management |
| Command | What it does |
|---|
leaderboard | Leaderboard operations |
tournament | Tournament bracket management |
matchmaking | Matchmaking service operations |
guild | Guild management |
quest | Quest engine: definitions, progress, expeditions, and puzzles |
achievement | Achievement engine management |
badge | Badge template registry, rendering, and verification |
lottery | Lottery operations (weighted random selection) |
| Command | What it does |
|---|
reputation | Reputation - Domain trust scores and pairwise affinity |
ritual | Synchronized multi-party ritual operations |
rumor | Rumor - Information propagation over graphs |
pact | Pact - multi-party staked agreements with signatures and obligations |
biome | Population dynamics simulation (biomes) |
seedling | Seedling - Deterministic generation, minting, and provenance |
succession | Succession - inheritance and handover of ownership, roles, and assets |
talent | Talent tree progression, allocation, and respec |
almanac | World time, calendars, weather, and content windows |
| Command | What it does |
|---|
alias | Alias identity resolution (link, resolve, merge, proxies) |
attestation | Attestation - Prove external account ownership via posted proofs |
moniker | Naming and handle registration |
handshake | Handshake - bilateral negotiation and escrowed settlement |
term | Policy document publishing and consent tracking |
| Command | What it does |
|---|
waiting-room | Waiting room management |
tour | Product tour and onboarding progress tracking |
link | Link redirect & attribution management |
form | Schema-backed form intake and submissions |
poll | Poll, voting, and tally operations |
throttle | Rate limiting as a product: token-bucket plans and checks |
| Command | What it does |
|---|
narrative | Narrative Engine - Manage universes, actors, stories, sessions, and events |
lore | Lore - Interactive story runtime: sessions, player commands, checkpoints |
agent | Agent registry (create, list, resolve, update, delete agents) |
liveness | Entity liveness tracking |
geo | Geo-proximity operations |