CLI reference

The command reference for the PrimDB CLI. Login, link, status, deploy and env ship today; databases and domains are in the dashboard and over MCP.

On this page

Install
Auth
Projects
Command groups
Environment variables
Global flags
Exit codes
CI/CD

Honest note. The CLI is for automation, not for driving PrimDB by hand. It is a thin client over the same MCP tools your agent uses, so for interactive work the agent is strictly better: no install, and 110 tools instead of six. What an agent cannot do is run inside a pipeline and fail a build with an exit code — that is this tool's job. Shipped: login, link, status, deploy, env list, env set. The rest of this page — db, domains, deployments, dev — is a design reference for commands that are not built. There is no env pull and there will not be: nothing on the token surface returns an env VALUE, so a leaked token can set a secret but never read one back.

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