env — environments

asymmetric env operates on 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.

asymmetric env <subcommand> [options]

env spin

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.

# 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

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

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

asymmetric env status --json | jq '.[].members'

Empty:

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

env destroy

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.

asymmetric env destroy acme

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

env reset

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

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:

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.

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. Multi-clone env spin and env reset already work today.

​env spin

​env status

​env destroy

​env reset

​Ad-hoc environments

​Errors you might see

​Not yet