CLI

Install

Homebrew (macOS/Linux):

brew install capydatabase/tap/capydb

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

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

With go install:

go install github.com/capydatabase/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 projects set-environment <production|non_production>

Sets a project's environment label. non_production unlocks overwrite-restore (capydb restore --target-kind project); production keeps it locked. --project.

capydb regions 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 - project naming and placement
• --environment - environment label: production (default) or non_production (unlocks overwrite-restore)
• --postgres-version - Postgres major version: 16, 17, or 18 (platform default when omitted; fixed after creation - previews and restores inherit it)
• --env-file - target env file
• --yes - non-interactive; let CapyDB pick a region when none is 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 backups schedule get|set|disable

Manages the project's daily backup schedule. All three take --project.

• set: --hour (UTC hour, 0-23), --minute (0-59), --retention-days (1-365, server default when omitted), --label (optional label for scheduled backups)

capydb export

Queues a logical export (pg_dump custom-format archive) of the project database, waits for the job, and downloads the artifact. Exports stay downloadable for 7 days.

• --output - destination file (default <project>-<timestamp>.dump)
• --no-download - queue and wait, but skip the download
• --wait-timeout, --project

capydb export list

Lists the project's exports with state, size, and expiry. --project.

capydb export download

Downloads a completed export within its 7-day window.

• --export - export id (see capydb export list)
• --output, --project

capydb import

Imports data into the project's live database - the same blast radius as an overwrite restore, so it requires --confirm or, on an interactive terminal, retyping the project name (or yes) at the prompt.

• --source-url - source Postgres connection string (use the provider's direct endpoint - Neon -pooler hosts and Supabase's transaction pooler on port 6543 are rejected)
• --file - path to a pg_dump file to upload and import (custom format recommended: pg_dump -Fc); mutually exclusive with --source-url
• --recreate - drop and recreate the target database before import
• --confirm - confirm loading the imported data into the live database (for non-interactive/CI use)
• --follow - near-zero-downtime import: base-copy then stream the source's changes until capydb import cutover (source needs logical replication; incompatible with --file and --recreate)
• --wait, --project

capydb import follow-status

Shows progress of an in-progress follow import (phase, replication lag). --wait, --project.

capydb import cutover

Finishes a follow import: drains the stream and flips the project live (stop source writers first). Replacing the live database requires --confirm or the interactive typed-name confirmation. --wait, --project.

capydb import follow-abort

Cancels an in-progress follow import and cleans up the source replication slot. --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 - confirm overwriting the project database non-interactively (without it, an interactive terminal prompts you to retype the project name); once confirmed, the CLI mints the single-use project.restore_overwrite approval token the control plane requires and attaches it for you
• --allow-unverified - allow restoring from a backup that has not passed verification
• --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

Migrations from other providers

All capydb migrate subcommands work without CapyDB credentials - they operate on your repo and your old database.

capydb migrate scan

Classifies a repository (read-only, no network) across the migration axes - source provider, auth system, data-access layer - and emits a per-database migration plan.

• --portfolio - directory of sibling repos to check for other consumers of the same databases

capydb migrate deps

Swaps provider-specific packages for their standard-Postgres equivalents in package.json.

• --dir - project directory
• --dry-run - report without writing

capydb migrate codemod neon

Rewrites Neon serverless-driver usage to plain postgres/pg. Dry-run by default.

• --write - apply the changes

capydb migrate rls

Converts Supabase row-level-security policies to portable, vanilla Postgres. Reads a supabase/migrations directory (found automatically from a repo root), a schema dump, or any SQL files; writes an ordered SQL bundle plus a report describing the session context your application must set. See the full guide.

• --mode - vanilla (default: app.* session-setting accessors) or supabase-compat (an auth.* shim; policies port verbatim)
• --role-model - single (default: FORCE row security, app connects as owner) or split (app_user/app_service roles)
• --keep-for-all - keep FOR ALL policies instead of splitting them per command
• --no-service-escape - single role model: skip the setting-gated service bypass policies
• --out - output directory (default capyrls)

capydb migrate verify

Watches the OLD database after cutover to confirm nothing still writes to it.

• --source-url - the old database
• --watch, --interval - keep checking on a cadence
• --env-file - env files naming the old database (repeatable)

Jobs

capydb jobs get

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

capydb jobs list

Lists a project's recent jobs, newest first.

• --limit - maximum number of jobs to return (server default when omitted)
• --project

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)
• --read-only - run inside a READ ONLY transaction, so the server itself refuses every write (DML, DDL, TRUNCATE, SELECT INTO, sequence advancement). Recommended whenever the statement is not meant to change anything - the guarantee comes from the Postgres executor, not from inspecting the statement
• --json - raw JSON result
• --project

capydb metrics

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

capydb logs

Shows the project's Postgres log stream: a trailing window by default, or a live tail with --follow (Ctrl-C to stop). In JSON mode a tail emits one JSON document per entry (JSONL).

• --hours - trailing window in hours (default 1). Up to 720 (30 days) where the platform keeps a log archive; 168 (7 days) otherwise - windows older than 7 days are served from the archive
• --limit - maximum entries per fetch (server default when omitted, max 500)
• --severity - comma-separated severity filter (debug, log, info, notice, warning, error, fatal, panic, detail), e.g. --severity error,fatal
• --follow (-f) - keep the stream open and print new entries as they arrive
• --project

capydb advisor indexes

Suggests indexes from the predicates your queries actually filtered on. Each candidate is costed by building it as a hypothetical index, so nothing is created and nothing is written to your database

• safe to run against production. Requires the pg_qualstats extension, plus hypopg for size estimates; note that enabling pg_qualstats restarts the database.

• --min-filter - minimum average rows a predicate must filter to be considered (default 1000; lower it on a quiet database)

• --min-selectivity - minimum average selectivity percentage for a predicate to be considered (default 30)

• --project

capydb advisor index-hygiene

The other half of index advice: indexes your database pays for on every write and never reads. Reports indexes with no recorded scans, and indexes whose columns are the leading columns of another index on the same table, each with a ready-to-run DROP INDEX CONCURRENTLY statement. Read-only, and it needs no extensions.

UNIQUE, primary-key and exclusion indexes are never listed - they are constraints, not just access paths. Nothing is reported until a week of query statistics has accumulated, because Postgres does not record when an index was created and over a shorter window an index a monthly job uses looks identical to a dead one.

• --project

Alias: capydb advisor unused-indexes.

Alias for the group: capydb advise.

Schema and code generation

capydb schema dump

Writes the project's schema as canonical JSON - the same document the API serves, stable enough to commit and diff. Stdout by default.

• --out - write to a file instead of stdout
• --preview - dump a preview database instead of the project database
• --project

capydb schema diff

Diffs the live schema against a committed snapshot or against a preview database.

• --against - baseline snapshot file produced by capydb schema dump
• --against-preview - baseline preview database id
• --preview - diff a preview database instead of the project database
• --exit-code - exit 1 when differences are found (for CI)
• --project

capydb generate types|zod|drizzle

Generates typed source from the live schema - TypeScript interfaces, Zod schemas, or a Drizzle schema. The code is rendered server-side from the same schema document schema dump returns, so it never needs a direct database connection.

• --out - output file path (defaults to the generator's suggested filename)
• --print - print to stdout instead of writing a file
• --preview - generate from a preview database instead of the project database
• --style (types only) - capydb (default) or supabase, which is compatible with supabase-js generics
• --project

See the type generation guide.

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.

Credentials

capydb credentials rotate

Rotates the project's database password. With --grace-hours the outgoing credential keeps working for that long (a new database username is issued), so applications can pick the new string up before the old one stops. 0 is an immediate cutover; the maximum is 720 hours.

• --grace-hours - hours the outgoing credential stays valid (0-720)
• --confirm - skip the interactive prompt
• --wait, --wait-timeout (default 30m)
• --project

See the credential rotation guide.

Version upgrades

Minor and major releases move very differently - see the version upgrades guide.

capydb upgrade minor

Restarts the database onto the latest available minor (17.4 to 17.5). Minors are binary-compatible, so nothing is migrated - only the server binary changes, at the cost of a brief interruption to open connections. A paused database needs no action: it starts on the new minor when it next resumes.

• --wait, --wait-timeout (default 30m)
• --project

capydb upgrade preflight

Checks whether the database can move to a Postgres major. Nothing is changed, so it is safe to run repeatedly. The blocker that matters most in practice is extensions: if one you use has no build for the target major, migrating would leave your schema referencing types and functions that no longer exist.

• --target-major - the major to evaluate, e.g. 18
• --wait (default true), --wait-timeout (default 30m)
• --project

Executing a major upgrade is operator-assisted and is not a CLI verb.

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, netlify, or wrangler (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

--target wrangler prints a wrangler.jsonc fragment carrying the Hyperdrive binding for this project's Cloudflare integration - connection strings stay out of it, since that file gets committed. The wrangler dev local connection string is printed alongside on stderr. Requires an active Cloudflare integration whose Hyperdrive config already exists.

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.