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

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

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.

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.
`dev`	Open a public tunnel to a local port with the feedback overlay injected. See 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.
`notes`	List, resolve, and export feedback notes. See 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.

Environment variables

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.

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

View as Markdown