# CLI reference

> Install @primdb/cli, authenticate, and drive projects, deploys, data, env, logs, and notes from the terminal.

The `primdb` CLI is the primary developer interface for managing projects, deployments, environment variables, logs, data services, and feedback notes. It is a single Bun-compiled binary with no runtime dependency on the target machine.

## Install

```bash
npm install -g @primdb/cli
# or
bun install -g @primdb/cli
```

Config and credentials live under `~/.primdb/` (token encrypted at rest with a machine-specific key, files `chmod 600`, never cloud-synced).

## Auth

```bash
primdb login                 # interactive browser login
primdb login --token primdb_...  # non-interactive (CI/CD)
primdb logout                # delete stored credentials
primdb whoami                # print the authenticated user
```

## Projects

Each command resolves the active project in order: the `--project` flag, then `.primdb.json` in the current directory, then `defaultProject` in `~/.primdb/config.json`.

```bash
primdb init                  # create a new project + write .primdb.json
primdb link                  # link an existing project (picker)
primdb link --project <id|slug>  # link non-interactively
```

## Command groups

| Group | What it does |
| --- | --- |
| `deploy` / `deployments` / `promote` / `rollback` | Trigger builds, list deployments, approve previews, roll back. See [Deploy](https://primdb.com/docs/deploy). |
| `dev` | Open a public tunnel to a local port with the feedback overlay injected. See [Preview feedback](https://primdb.com/docs/preview-feedback). |
| `env` | Set, list, remove, pull, and push environment variables. |
| `logs` | Stream production or per-deployment logs (SSE), or print the last N lines. |
| `db` / `redis` / `storage` | Work with Postgres, Redis, and object storage. See [Data](https://primdb.com/docs/data). |
| `notes` | List, resolve, and export feedback notes. See [Preview feedback](https://primdb.com/docs/preview-feedback). |
| `domains` | Add, verify, and remove custom domains (TLS via Let’s Encrypt once DNS verifies). |
| `users` | Manage the end-users of your deployed app. See [Auth](https://primdb.com/docs/auth). |

## Environment variables

```bash
primdb env set KEY=VALUE            # set a variable
primdb env set KEY=VALUE --secret   # mark as secret (masked in dashboard + logs)
primdb env list                     # list all vars (values masked)
primdb env list --reveal            # list with values visible
primdb env rm KEY                   # delete a variable
primdb env pull                     # download all vars to .env.local
primdb env push                     # upload vars from .env.local
```

## Global flags

| Flag | Short | Description |
| --- | --- | --- |
| `--project <id|slug>` | `-p` | Override the project (default: from `.primdb.json`) |
| `--token <token>` |  | Override the auth token (default: from `~/.primdb/credentials.json`) |
| `--json` |  | Output raw JSON instead of formatted text (for scripting/CI) |
| `--no-color` |  | Disable ANSI color codes |
| `--debug` |  | Verbose logging (requests, responses, timing) |

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | General error (build failed, resource not found, etc.) |
| `2` | Auth error (not logged in, token expired or revoked) |
| `3` | Network error (relay unreachable, timeout) |
| `4` | Validation error (bad arguments, missing required flags) |

## CI/CD

Authenticate non-interactively with a repository secret, then deploy and wait. Exit code reflects the build outcome.

```yaml
- name: Deploy to PrimDB
  env:
    PRIMDB_TOKEN: ${{ secrets.PRIMDB_TOKEN }}
  run: |
    primdb login --token $PRIMDB_TOKEN
    primdb deploy --wait
```

---

Source: https://primdb.com/docs/cli