> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getasym.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> Every asymmetric command, global behavior, and exit codes.

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

## A typical session

```bash theme={null}
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
```