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

# CLI overview

> Every hone env command, global behavior, and exit codes.

```
hone env <command> [args] [options]
```

Environment commands live under the **`hone env`** group of the `hone` CLI
(`@asymmetric-ai/hone-cli`). The retired standalone bin `asym` is kept as a
deprecated alias — it prints a rename notice, then delegates, so old scripts
keep working. 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 `hone env ls --templates`.

## Commands

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

All commands above are invoked as `hone env <command>`. `--json` is available on
`spin`, `seed`, `status`/`ls`, `query`, `db`, `tokens`, `verify`, and `doctor`
(including their environment-composition forms) 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 `hone env status`.

**Errors are sentences, not stacks.** Every failure is a
[named error](/environments/reference/errors) rendered as one actionable line — e.g. *"Docker
isn't running. Start it, then retry. (hone env 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](/environments/concepts/clones#the-registry).

## A typical session

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