> ## 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.

# env — environments

> Spin, list, reset, and tear down environments — named compositions of clones.

`asymmetric env` operates on [environments](/concepts/environments): named
compositions of clones. An environment's membership is the source of truth, so
these commands work at the environment level instead of clone by clone.

```bash theme={null}
asymmetric env <subcommand> [options]
```

## env spin

```bash theme={null}
asymmetric env spin <file> [--json]
```

Validate an `environment.yaml`, spin **every clone it declares** (in order), and
record the environment with those clones as members. The spec's path is stored on
the environment as its `source`.

```yaml theme={null}
# acme.env.yaml
name: acme
clones:
  - template: slack
    mode: api
    seed: acme-corp        # optional: a named fixture to seed on create
  - template: stripe
    mode: api
```

```bash theme={null}
asymmetric env spin acme.env.yaml
```

```
✓ environment acme [running]: 2/2 clone(s) up
  ✓ slack-a1b2  http://127.0.0.1:3001/api
  ✓ stripe-c3d4  http://127.0.0.1:3002/api
```

Clones are spun **sequentially, continue-all**: each one is created and joins the
environment before the next starts, so a sibling's ports are committed before the
next is allocated. If a member fails, the others still come up, the failure prints
to stderr, the environment is stamped `partial`, and the command exits `1`.

The spec is **strict** — anything not yet supported is a clear error, not a silent
no-op:

| In the spec                   | Result                                                      |
| ----------------------------- | ----------------------------------------------------------- |
| Unknown key (e.g. `clone:`)   | `Unknown key(s): 'clone' (did you mean 'clones'?)`          |
| Empty `clones` (zero entries) | Hard error — a spec must declare at least one clone.        |
| `identity:` / `data:` blocks  | Hard error — shared identity / BYOD data not supported yet. |
| Malformed or empty YAML       | A clear `ENV_SPEC_INVALID` error.                           |

## env status

```bash theme={null}
asymmetric env status [--json]
asymmetric env ls [--json]
```

List environments, one per line: name, rolled-up state, and members.

```
acme	running	2 member(s): slack-a1b2, stripe-c3d4
```

```bash theme={null}
asymmetric env status --json | jq '.[].members'
```

Empty:

```
No environments. Create one:  asymmetric env spin <environment.yaml>
```

## env destroy

```bash theme={null}
asymmetric env destroy <name>
```

Destroy every clone in the environment (containers down, database dropped, ports
freed). Continue-all: each member is attempted even if one fails, failures print
to stderr, and the command exits `1` if any member failed. Removing the last
member drops the environment.

```bash theme={null}
asymmetric env destroy acme
```

```
✓ environment acme: destroyed 2/2 clone(s)
```

## env reset

```bash theme={null}
asymmetric env reset <name> [--json]
```

Reset every clone in the environment to its clean seeded state — each member is
dropped, re-migrated, and re-seeded (the same as [`reset <id>`](/cli/lifecycle#reset),
applied across the whole environment). Continue-all: every member is attempted,
failures print to stderr, and the command exits `1` if any member failed. The
environment is stamped `running` when all members reset, `partial` if any failed.

```bash theme={null}
asymmetric env reset acme
```

```
✓ environment acme [running]: reset 2/2 clone(s)
```

## Ad-hoc environments

You don't need a spec file. Tag clones into an environment as you spin them — each
joins the named environment:

```bash theme={null}
asymmetric spin slack slack --group acme
```

Both clones become members of environment `acme` (with `spec: null`), and the
`env status` / `env destroy` commands operate on them as a unit.

## Errors you might see

| Error                | Cause                                                                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `ENV_SPEC_INVALID`   | The `environment.yaml` is unreadable, malformed, has an unknown key, or uses a not-yet-supported section. The message says exactly what to fix. |
| `DOCKER_UNAVAILABLE` | Docker isn't running.                                                                                                                           |
| `TEMPLATE_NOT_FOUND` | A `clones[].template` isn't in the catalog.                                                                                                     |

See the [full error reference](/reference/errors).

## Not yet

Two declared-but-not-yet-enforced spec sections fail loudly rather than silently
no-op: **shared `identity:`** across clones, and **bring-your-own `data:`**
(an external Postgres). Both are on the roadmap — see
[Environments](/concepts/environments#on-the-roadmap). Multi-clone `env spin` and
`env reset` already work today.