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

# CLI

> shipd command-line interface: auth, pull, diff, push, types, snapshots.

## Overview

```bash theme={null}
pnpm add -g @shipdit/cli
shipd --help
```

Binary: `shipd`. Package: `@shipdit/cli`. Every command works non-interactively and supports `--json`.

## Global flags

| Flag                    | Purpose                                                                    |
| ----------------------- | -------------------------------------------------------------------------- |
| `--json`                | Machine-readable stdout (errors on stderr as JSON)                         |
| `--yes` / `--ci`        | Skip confirmation (`CI=1` / `SHIPD_CI=1` also)                             |
| `--api-url <url>`       | API origin (`SHIPD_API_URL`; login defaults to `https://api.useshipd.com`) |
| `--org <slug>`          | Organization (`SHIPD_ORG`)                                                 |
| `--project <slug>`      | Project (`SHIPD_PROJECT`)                                                  |
| `--env <slug>`          | Environment (`SHIPD_ENV`)                                                  |
| `--config <path>`       | Project settings JSON (`.shipd/config.json` shape)                         |
| `--flags-config <path>` | Path to `shipd.config.ts`                                                  |

Precedence (highest wins): CLI flags → env (`SHIPD_*`) → `.shipd/config.json` → `~/.config/shipd/`.

Credentials: `~/.config/shipd/credentials.json` (mode `0600`). XDG: `$XDG_CONFIG_HOME/shipd`.

## Auth

| Command        | Description                                                                          |
| -------------- | ------------------------------------------------------------------------------------ |
| `shipd login`  | Device authorization at `/auth/device/code`. Stores a scoped **management** API key. |
| `shipd logout` | Clear stored credentials                                                             |
| `shipd whoami` | Current user or API-key context                                                      |

Login opens org → project → environment. That binding is the key's environment.

## Config as code

| Command           | Description                                         |
| ----------------- | --------------------------------------------------- |
| `shipd pull`      | Rewrite `shipd.config.ts` from the server + typegen |
| `shipd push`      | Plan and apply                                      |
| `shipd diff`      | Show plan (`--json`)                                |
| `shipd types gen` | Typegen from local config (`-o, --out`)             |

### Push flags

| Flag             | Meaning                              |
| ---------------- | ------------------------------------ |
| `--prune`        | Archive remote flags missing locally |
| `--force`        | Override stale-version CAS (audited) |
| `--adopt`        | Deprecated no-op                     |
| `--yes` / `--ci` | Skip confirmation                    |

Removes are **archives**. Definition changes need `flag.production.toggle`. Default-only non-prod needs `flag.state.update`.

```text theme={null}
Plan:
  + create flag "new-checkout"
  ~ update flag "search-variant"
      description: "Old" -> "New"
      tags: ["search"] -> ["search", "experiment"]
  - archive flag "legacy-homepage"
```

```json theme={null}
{
  "creates": [],
  "updates": [],
  "archives": [],
  "unlinked": [],
  "conflicts": []
}
```

## Snapshots

```bash theme={null}
shipd snapshots publish --project web-app --env production
```

Materialize from Postgres and publish to KV. Use after a failed publish.

## Lower-level

| Command                   | Description                                                                                  |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| `shipd flags list`        | List flags                                                                                   |
| `shipd flags create`      | `--key` required; `--type boolean\|variant\|number\|json`; `--variants` required for variant |
| `shipd flags archive`     | Archive by `--key`                                                                           |
| `shipd projects list`     | List projects                                                                                |
| `shipd environments list` | List environments                                                                            |

## CI

```bash theme={null}
SHIPD_API_KEY=shipd_mgmt_… shipd push --yes
shipd push --ci --project web-app --org fieldkit --env production
```

The key's environment **must** match `--env`. `--org` cannot switch organizations.

## Exit codes

| Code | Meaning                        |
| ---- | ------------------------------ |
| 0    | Success / no drift             |
| 1    | General error                  |
| 2    | Drift (`diff --exit-code`)     |
| 3    | Conflict (stale version / CAS) |
| 4    | Unlinked (`diff --exit-code`)  |

Guides: [Define flags](/guides/define-flags) · [CI](/guides/ci).