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

# CLI Setup

> Install, authenticate, and start creating context topics.

## Install

```bash theme={"theme":"github-light"}
npm install -g @driftless-sh/cli
```

## Authenticate

Run `driftless login` to open your browser to the Driftless dashboard, where you can copy your API key:

```bash theme={"theme":"github-light"}
driftless login
```

For non-interactive environments (e.g., CI), pass the key directly:

```bash theme={"theme":"github-light"}
driftless login --key drift_xxxxxxxxxxxxxxxxx
```

## Install the agent skill

Install Driftless context instructions so coding agents automatically retrieve topics before editing:

```bash theme={"theme":"github-light"}
driftless install-skill
```

This writes `AGENTS.md` and `CLAUDE.md` into your repo. Agents will see topic retrieval instructions every session.

## Create your first topic

Driftless starts with topics: durable engineering memory anchored to the files and workflows where it matters.

```bash theme={"theme":"github-light"}
# First topic = something REAL you already know, anchored to the module it governs:
driftless context add api-auth --title "Auth" \
  --what "Every API request is workspace-scoped by a global guard." \
  --pattern "src/auth/**"
```

Nothing concrete to record yet? Skip it. Work first and persist what you learn. A generic placeholder topic documents nothing and rots on day one.

Enrich with structured context:

```bash theme={"theme":"github-light"}
driftless context update api-auth \
  --gotcha "WorkspaceGuard is global, use @Public() only for explicit public routes" \
  --decision "RS256 keys so services verify without shared secret" \
  --invariant "All routes require auth unless explicitly marked @Public()" \
  --check "Verify role decorator matches the guard's expected metadata"
```

Connect topics with typed relations:

```bash theme={"theme":"github-light"}
driftless context update api-auth --rel relates_to:api-architecture
driftless context get api-auth --json
```

Anchor to file paths for drift tracking:

```bash theme={"theme":"github-light"}
driftless context update api-auth \
  --add-pattern "src/auth/guards/**"
```

The CLI validates each pattern against your local checkout at write time. A pattern that matches zero files is blocked; one that matches over 100 files gets an over-broad warning.

<Note>
  Set `DRIFTLESS_API_KEY` for non-interactive environments. Set `DRIFTLESS_API_URL` only when targeting staging or a local API.
</Note>

## Config File

The CLI stores its state in `~/.driftless/config.json`:

```json theme={"theme":"github-light"}
{
  "api_key": "drift_xxxxxxxxxxxxxxxxx",
  "api_url": "https://api.driftless.icu/api/v1",
  "workspace_slug": "acme-corp",
  "workspace_id": "ws_abc123"
}
```

## Command reference

| Command         | Flags         | Description                   | Example                           |
| --------------- | ------------- | ----------------------------- | --------------------------------- |
| `login`         | `--key <key>` | Authenticate with API key     | `driftless login --key drift_xxx` |
| `doctor`        | `--json`      | 8 health checks               | `driftless doctor`                |
| `install-skill` | none          | Install AGENTS.md + CLAUDE.md | `driftless install-skill`         |

## Global flags

| Flag               | Description           |
| ------------------ | --------------------- |
| `--version` / `-v` | Print version         |
| `--help` / `-h`    | Full help             |
| `<cmd> --help`     | Command-specific help |

<AccordionGroup>
  <Accordion title="Environment Variables">
    | Variable            | Description                                                  |
    | ------------------- | ------------------------------------------------------------ |
    | `DRIFTLESS_API_KEY` | API key (wins over config file)                              |
    | `DRIFTLESS_API_URL` | API server URL (default: `https://api.driftless.icu/api/v1`) |
  </Accordion>
</AccordionGroup>