CLI overview - asymmetric

asym <command> [args] [options]

The CLI installs two equivalent binaries: asym (short, recommended) and asymmetric (alias). Use whichever you like — every example below works with either. Every clone-scoped verb takes a clone id (like slack-a1b2); spin and verify take a template name (like slack). Six templates ship today — slack, stripe, linear, github, notion, and hubspot. List them anytime with asym ls --templates.

Commands

Command	What it does	Status
`quickstart`	One command: spin a Slack clone, seed it, print how to use it.	✅
`spin <template...>`	Create and start one or more clones.	✅
`env <spin\|status\|reset\|destroy>`	Spin, list, reset, and tear down environments (compositions of clones).	✅
`seed <id>`	Load fixtures and/or generate AI data.	✅
`query <id> [sql]`	Run SQL against a clone (read-only by default).	✅
`db <id>`	Print the `psql` command for a clone’s database.	✅
`tokens <id>`	Print (or `--reprovision`) a clone’s bot + user API tokens.	✅
`reset <id>`	Drop, re-migrate, and re-seed to a clean state.	✅
`start <id>`	Start a stopped clone.	✅
`stop <id>`	Stop a clone, keep its data.	✅
`destroy <id>`	Tear down containers, drop db, free ports.	✅
`status`	List clones (alias `ls`); `ls --templates` lists what you can spin.	✅
`logs <id>`	Stream a clone’s container logs.	✅
`doctor`	Reconcile the registry against Docker (`--fix` to repair).	✅
`verify <template>`	Inspect a template’s live API surface + cached fidelity.	✅
`completion`	Print a shell completion script.	✅
`login`	Connect to a control plane (cloud mode). Local needs no login.	🚧 Cloud mode planned

--json is available on spin, env spin/env status/env reset, seed, status/ls, query, db, tokens, verify, and doctor for scripting.

Global behavior

One id, every command. Clone-scoped verbs fail fast with CLONE_NOT_FOUND if the id isn’t in your registry, and point you to asymmetric status. Errors are sentences, not stacks. Every failure is a named error rendered as one actionable line — e.g. “Docker isn’t running. Start it, then retry. (asymmetric doctor)” Exit codes:

Code	Meaning
`0`	Success.
`1`	A known, user-actionable error (a named `AsymmetricError`), or a per-template failure during `spin`.
`2`	Bad invocation (e.g. `query` with no SQL, or `--json` + `--write`), or an unexpected failure.

State location. All state is under ~/.asymmetric/ (override with ASYM_HOME). See the registry.

A typical session

asymmetric spin slack --seed acme-corp   # create + seed in one step
asymmetric status                         # confirm it's running
asymmetric query slack-a1b2 "select count(*) from messages"
# ... point your agent at the endpoint ...
asymmetric query slack-a1b2 "select * from messages" --json   # score the run
asymmetric reset slack-a1b2               # back to clean, for the next trial
asymmetric destroy slack-a1b2             # done

​Commands

​Global behavior

​A typical session

Commands

Global behavior

A typical session