CLI

Install

Homebrew (macOS/Linux):

brew install capy-base/tap/capydb

Curl installer (verifies the release checksum, installs to /usr/local/bin or $CAPYDB_INSTALL_DIR):

curl -fsSL https://raw.githubusercontent.com/capy-base/capydb-cli/main/scripts/install.sh | sh

With go install:

go install github.com/capy-base/capydb/cli/cmd/capydb@latest

Release archives are built for macOS, Linux, and Windows. Tagged releases also publish checksums, SBOMs, a container image, and the Homebrew cask.

Global flags

Every command accepts:

• --output text|json (-o) — human-readable text or machine-readable JSON. In JSON mode stdout carries only the JSON document, and lists always marshal as [], never null
• --api-url — CapyDB API base URL (defaults to https://capydb.dev/api/capydb)
• --api-key — organization or project-scoped API key (or set CAPYDB_API_KEY)
• --app-url — CapyDB app URL for browser-based login and dashboard links (or CAPYDB_APP_URL)

Without a saved login or key, commands fail fast with no api key available; pass --api-key, set CAPYDB_API_KEY, or run 'capydb login' instead of hanging.

Commands that queue async jobs (create, preview create|delete|reset, backups create, import, restore, extensions enable|disable, jobs get) accept --wait plus --wait-timeout (default 30m). CAPYDB_HTTP_TIMEOUT (a Go duration such as 45s or 2m) overrides the API and upload timeouts.

Exit codes

Auth

capydb login

Opens a browser device-login flow, authorizes against the active dashboard organization, and saves a CLI key locally.

• --no-open — print the authorization URL without opening a browser
• --name — human-readable name for the CLI key
• --device-name — device label stored with the key
• --expires-in — key lifetime such as 24h, 7d, 30d, or an RFC 3339 timestamp

capydb logout

Clears saved CLI authentication.

capydb whoami

Shows the current CLI identity (org, key, source).

capydb status

Shows saved auth, the local project link, and optionally remote status:

• --remote — check the API and the linked project
• --project — project id, slug, or name for remote status

capydb doctor

Checks config, API reachability, auth, the local project link, and psql availability in one pass. Non-zero exit when any check fails — useful as the first command in a broken environment.

capydb config show

Prints the resolved configuration. The API key is shown only as a ****abcd fingerprint.

capydb version [--check]

Build info. --check compares against the latest GitHub release (5s timeout, degrades to a warning offline).

capydb orgs list / capydb orgs switch <org-id|slug>

The CLI stores credentials per organization with an active-org pointer; switch changes which one subsequent commands use.

Compatibility aliases: capydb auth login|logout|whoami.

Projects and linking

capydb projects list

Lists the organization's projects (id, name, slug, region, state).

capydb clusters list

Lists the active regions projects can be placed on.

capydb create

Creates a project and links the current directory to it (power-user path; the dashboard is the default onboarding).

• --name, --slug, --region, --cluster — project naming and placement
• --env-file — target env file
• --yes — non-interactive; use the first cluster when none specified

Alias: capydb init.

capydb link

Links the current directory to an existing project. Accepts a project id, slug, or name via --project; prompts interactively on multiple matches; reuses .capydb/project.json when present.

• --project — project id, slug, or name
• --env-file — target env file

It detects the local app profile (Next.js, SvelteKit, Remix, Django, Rails, Go, generic Node/Python; Prisma, Drizzle, pg, pgx, SQLAlchemy, Active Record), writes DATABASE_URL / DATABASE_DIRECT_URL / DATABASE_POOL_URL (plus aliases like DIRECT_URL for Prisma) into the right env file, saves a non-secret link in .capydb/project.json, and gitignores both .capydb/ and the credential-bearing env file. Monorepos: nested app directories are detected and prompted for.

Alias: capydb connect.

capydb unlink

Removes the local project link.

capydb env pull

Refreshes local env vars from the linked project (after a rotation, restore, or import).

• --env-file — override the target env file

Previews

capydb preview list

Lists preview databases with state, mode, TTL expiry, and connection URLs. --project to target a specific project.

capydb preview create

• --mode — empty or clone
• --name — preview name
• --ttl-hours — TTL in hours (1–168, default 24)
• --wait — block until the create job finishes
• --project

capydb preview reset

Re-clones or re-empties a preview. --preview (id or name), --wait, --project.

capydb preview delete

--preview (id or name), --wait, --project.

capydb preview extend <preview-id>

• --ttl-hours — new TTL in hours (1–168)

Backups, restores, imports

capydb backups list / capydb backups create

• create: --label (optional), --wait, --project

capydb import

• --source-url — source Postgres connection string (must be publicly reachable)
• --recreate — drop and recreate the target database before import
• --wait, --project

capydb import preflight

Checks a source database against the project before importing — size vs plan, Postgres major (no downgrades), extension availability — without changing anything.

• --source-url, --project

capydb restore

• --backup-key — backup to restore
• --restore-time — RFC 3339 timestamp for point-in-time restore
• --restore-point — labelled restore point id (alternative to the two above)
• --target-kind — project, preview, or new_preview (inferred from --preview/--preview-name; defaults to new_preview)
• --preview — existing preview id or name (target-kind preview)
• --preview-name — name for a new preview (target-kind new_preview)
• --ttl-hours — TTL for the new preview
• --confirm-project-overwrite — required when overwriting the project database
• --recreate — recreate the target before restore
• --wait, --project

capydb restore-points list|create|delete

• create: --label (required), --kind (backup or pitr, inferred), --backup-key, --pitr-time (defaults to now), --note
• delete: --id

Jobs

capydb jobs get

• --job-id — job to inspect
• --wait — block until terminal state before printing

Database access

capydb connection-string

Prints only the URL — script-friendly.

• --pooled — pooled (pgbouncer) URL instead of direct
• --preview — preview database id
• --project

capydb psql [-- <extra psql args>]

Opens psql against the project or a preview. --pooled, --preview, --project.

capydb sql <query>

Runs a query through the bounded SQL runner (15s timeout, 1000-row cap, 20k-char queries).

• --max-rows — row cap (server default 200 when omitted)
• --json — raw JSON result
• --project

capydb metrics

Storage/connection usage, alerts, active and slow queries. --json for the raw payload. Alias: capydb observability.

Extensions

capydb extensions list|enable|disable

Manages the project's Postgres extensions. list shows the allowlist with enabled/trusted/version per extension; enable <name> and disable <name> queue async jobs and accept --wait. Disable runs DROP EXTENSION without CASCADE, so it fails (with the dependency error) rather than dropping dependent objects. --project on all three. Aliases: extension, ext.

Alerts

capydb alerts list

Lists the project's threshold alerts — open ones plus those resolved in the last 30 days — with kind, severity, observed/limit values, and timestamps. --project.

capydb alerts ack <alert-id>

Acknowledges an alert (idempotent; first acknowledgement time wins). Acknowledging is visual only — it does not silence notifications. --project. Alias: acknowledge.

Audit

capydb audit list

Lists project audit events. --project, --limit N.

API keys

capydb api-keys list|create|revoke

• create: --name and --scopes are required; --project makes the key project-scoped. The plaintext key is shown exactly once.
• revoke: by key id.

Webhooks

capydb webhooks list|create|delete|rotate-secret|deliveries

Manages the organization's webhook endpoints. Signing secrets (whsec_...) are shown exactly once on create and rotate; deliveries shows the per-endpoint delivery history.

Misc

capydb studio

Opens the dashboard page for the linked project.

• --page — overview, connections, studio, previews, backups, or settings (default connections)
• --print-only — print the URL without opening it
• --project

capydb integrations env

Prints environment-variable payloads for deployment platforms.

• --target — dotenv, json, vercel, or netlify (default dotenv)
• --branch — Vercel preview branch for branch-scoped env vars
• --netlify-context — all, dev, branch-deploy, deploy-preview, production, or branch (default all)
• --project

capydb completion bash|zsh|fish|powershell

Shell completion scripts. Release archives and the Homebrew cask ship pre-generated ones.

Local files

• Global: CLI auth and active organization info live in the user config directory.
• Local: .capydb/project.json stores the linked project id, chosen env file, and detected profile — no secrets. Secrets stay in the app env file, which the CLI gitignores.