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

# Installation

> Install the asymmetric CLI from npm and get it on your PATH.

The CLI is published to npm as **`@asymmetric-ai/cli`** and is free to use. Install
it, make sure Docker is running, and you're ready to spin clones. Clone images are
pulled for free on first use — nothing is built locally.

## Requirements

| Tool                                          | Version | Why                                                                                                             |
| --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| [Docker](https://docs.docker.com/get-docker/) | running | Clones run as containers; spin shells out to `docker` and `docker compose`.                                     |
| Node.js                                       | `>= 18` | Runs the CLI (`npx` / `npm install -g`).                                                                        |
| `psql` client                                 | any     | Only if you run `asym db` and want a local shell; `query` runs `psql` *inside* the container, so it's optional. |

An `ANTHROPIC_API_KEY` is needed only for [AI seeding](/concepts/seeding).

## Install

Run it with no install at all:

```bash theme={null}
npx @asymmetric-ai/cli quickstart
```

Or install it globally:

```bash theme={null}
npm install -g @asymmetric-ai/cli
```

The package installs **two equivalent commands**: `asym` (recommended, used
throughout these docs) and `asymmetric` (an alias). Use whichever you like.

## Verify the install

```bash theme={null}
asym --version
asym doctor
```

`doctor` reconciles your local registry against Docker and reports the basics:

```
home:    /Users/you/.asymmetric (local)
docker:  available
shared:  postgres unknown
clones:  0  environments: 0
```

If `doctor` runs, you're set. Head to the [Quickstart](/quickstart).

## Where state lives

asymmetric keeps everything under `~/.asymmetric/`:

| File            | Holds                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| `config.json`   | Your profile, control-plane URL/token, and the port range (default `3000–3999`).                                   |
| `registry.json` | Every clone and environment, with ids, ports, database names, state, and seed. Schema-versioned; migrated on read. |

Override the location with the `ASYM_HOME` environment variable — useful for
isolating CI runs from your local clones.

<Note>
  Local mode needs no account or login. `asym login` only matters for the planned
  connected/cloud mode.
</Note>