CLI Reference

The db9 CLI is the primary interface for creating databases, running SQL, managing files, branching, and onboarding AI agents. This page is a complete command reference.

Common Journeys

I want to…	Start here
Try DB9 in under two minutes	Quick Start
Connect an ORM or driver	Connect
Understand the architecture	Architecture
Set up DB9 for Claude Code or Codex	Agent Workflows
Create databases programmatically	Provisioning
Inspect query performance	Inspect & Observability below
Run SQL from the terminal	SQL Execution below
Upload files to a database	Filesystem below
Create a branch for testing	Branching below
Schedule recurring SQL jobs	Cron Jobs below
Prepare for production	Production Checklist

Installation

Install with the official script (Linux/macOS, amd64/arm64):

Terminal

curl -fsSL https://db9.ai/install | sh

To control where binaries land, set DB9_INSTALL_DIR:

Terminal

DB9_INSTALL_DIR="$HOME/.local/bin" curl -fsSL https://db9.ai/install | sh

Verify:

Terminal

db9 --version
db9 status

The installer places db9 (and optionally db9-fuse for FUSE mounts) into your chosen directory.

Global Flags

These flags apply to every db9 command:

Flag	Env Variable	Default	Description
--api-url <URL>	DB9_API_URL	https://api.db9.ai	API base URL
--output <FORMAT>	—	table	Output format: table, json, or csv
--json	—	—	Shorthand for --output json
--insecure	DB9_INSECURE	—	Skip TLS certificate verification

Authentication

DB9 supports three auth paths: anonymous trial, SSO login, and API key (CI/agents). Tokens are stored in ~/.db9/credentials.

Security: Treat DB9_API_KEY as a secret. Never send your token to any domain other than api.db9.ai.

Terminal

# Zero-setup trial (auto creates anonymous account + token)
db9 create --name quickstart

# Upgrade anonymous account to verified SSO identity
db9 claim
db9 claim --id-token <AUTH0_ID_TOKEN>

# Human operator login (browser-based)
db9 login

# API key login (CI/CD, agents)
db9 login --api-key <KEY>

# Agent runtime
export DB9_API_KEY=<token>

See Token Management for creating automation tokens.

Setup & Utilities

Terminal

# Guided setup: login and create your first database
db9 init

# Set or show default database (omit DB to show current)
db9 use <db>
db9 use --clear

# Remove stored credentials
db9 logout

# Update db9 (and db9-fuse) to the latest version
db9 update

# Generate shell completion scripts
db9 completion bash
db9 completion zsh

# Show / set CLI configuration
db9 config show
db9 config set api_url https://api.db9.ai

Database Lifecycle

Database commands accept <db> as a database name (preferred) or ID. When omitted, the default database set by db9 use is used.

These are top-level commands — use db9 create, not db9 db create.

Terminal

# Create (name is optional; will auto-generate if omitted)
db9 create --name myapp
db9 create --name myapp --region us-west
db9 create --name myapp --show-secrets   # print password & connection string

# List
db9 list

# Check login status
db9 status

# Show database status
db9 db status <db>

# Print passwordless connection info (psql-compatible)
db9 db connect <db>

# Create a short-lived connect token (10-min TTL, for psql/ORM usage)
db9 db connect-token <db>
db9 db connect-token <db> --role app_user

# Reset admin password
db9 db reset-password <db>

# Delete (prompts unless you pass --yes)
db9 delete <db> --yes

Deprecated forms: db9 db create, db9 db list, db9 db delete, and db9 db branch still work but print a deprecation warning. Use the top-level forms instead.

For programmatic database creation patterns, see Provisioning.

Inspect and Observability

Terminal

# Overview metrics
db9 db inspect <db>

# Subcommands
db9 db inspect <db> queries        # query samples and performance
db9 db inspect <db> report         # combined summary + queries report
db9 db inspect <db> schemas        # list database schemas
db9 db inspect <db> tables         # list database tables
db9 db inspect <db> indexes        # list database indexes
db9 db inspect <db> slow-queries   # slow queries sorted by p99 latency

For production monitoring guidance, see Production Checklist.

Database Users

Terminal

# List database users
db9 db users <db> list

# Create a new database user (password auto-generated if omitted)
db9 db users <db> create --username app_user --password 'SecurePass1'

# Delete a database user
db9 db users <db> delete --username app_user

SQL Execution

Run SQL via inline query (-q), file (-f), stdin, or an interactive REPL. Use -D for direct pgwire mode. The <db> argument is optional — if omitted, the CLI auto-selects the default database or prompts interactively.

Terminal

# Inline
db9 db sql <db> -q "SELECT now()"

# From file
db9 db sql <db> -f ./query.sql

# From stdin
cat ./query.sql | db9 db sql <db>

# Interactive REPL (TTY only)
db9 db sql <db>

# Direct mode (pgwire)
db9 db sql <db> -D
db9 db sql <db> -D --dsn "postgresql://..."

# Execute a seed SQL file
db9 db seed <db> ./seed.sql

# Export database schema (and optionally data) as SQL
db9 db dump <db>
db9 db dump <db> --ddl-only
db9 db dump <db> -o ./backup.sql

Filesystem

Each database has a remote filesystem. Use db9 fs for shell access, file copy, and (optionally) FUSE mounts.

Terminal

# Interactive filesystem shell
db9 fs sh <db>

# Run a single command (bash -c style)
db9 fs sh <db> -c "ls -la"

# Upload / download (scp-like)
db9 fs cp ./local.txt <db>:/remote/path/local.txt
db9 fs cp <db>:/remote/path/remote.txt ./remote.txt

# Recursive upload / download (directories)
db9 fs cp -r ./imports <db>:/data/imports

# Glob upload / multi-file upload
db9 fs cp ./*.go <db>:/remote/
db9 fs cp a.go b.go <db>:/remote/

# Mount via FUSE (requires db9-fuse and system FUSE support)
db9 fs mount <db> "$HOME/mnt/mydb"
db9 fs mount <db> "$HOME/mnt/mydb" --read-only
db9 fs mount <db> "$HOME/mnt/mydb" --cache-ttl 30
db9 fs mount <db> "$HOME/mnt/mydb" -f            # foreground

Advanced filesystem flags (all fs subcommands): --ws-url <URL> (direct WebSocket URL), --ws-port <PORT> (default: 5480).

For querying files with SQL, see fs9 extension.

Migrations

Manage local migration files and apply them to a database. Default directory is ./migrations.

Terminal

# Create a new migration file
db9 migration new create_users

# List local migration files
db9 migration list

# See applied vs pending
db9 migration status <db>

# Apply pending migrations
db9 migration up <db>

All migration subcommands accept --dir <path> to override the default ./migrations directory.

Branching

Branches are schema copies used for safe experimentation. Branch commands are top-level under db9 branch.

Terminal

# Create a branch from an existing database
db9 branch create <db> --name feature1
db9 branch create <db> --name feature1 --show-secrets

# List branches of a database
db9 branch list <db>

# Delete a branch database
db9 branch delete <branch_db>

For branch-based workflows (preview environments, rollback, task isolation), see Multi-Tenant Patterns.

Cron Jobs

Schedule SQL with pg_cron (extension required). Cron commands live under db9 db cron.

Terminal

# List jobs
db9 db cron <db> list

# Create (schedule + SQL command)
db9 db cron <db> create "*/5 * * * *" "SELECT 1"

# Create from file (optional name enables upsert semantics)
db9 db cron <db> create "0 * * * *" --name hourly_job -f ./job.sql

# History / status
db9 db cron <db> history --limit 20
db9 db cron <db> status

# Enable / disable / delete by job id or job name
db9 db cron <db> disable <job>
db9 db cron <db> enable <job>
db9 db cron <db> delete <job>

For scheduling patterns and operational guidance, see pg_cron extension.

Token Management

Create and manage API tokens for CI/CD pipelines, automation, and agent workflows.

Terminal

# Show the current raw token (for use with DB9_API_KEY)
db9 token show

# Create a new API token (default: 365-day expiry)
db9 token create --name my-agent
db9 token create --name ci-token --expires-in-days 90

# List your API tokens
db9 token list

# Revoke a token
db9 token revoke <token_id>

Store created tokens in a secret manager. See Production Checklist for token security guidance.

Type Generation

Generate types from the live schema (prints to stdout). Available languages: TypeScript and Python.

Terminal

# TypeScript
db9 gen types <db> --lang typescript --schema public > db9.types.ts

# Python
db9 gen types <db> --lang python --schema public > db9_types.py

Agent Onboarding

db9 onboard installs or updates the DB9 skill into supported local coding agents. It does not require login and does not send tokens anywhere.

Terminal

# Interactive wizard
db9 onboard

# Non-interactive
db9 onboard --yes --all
db9 onboard --yes --agent codex --agent claude --scope user

# Safety / introspection (zero filesystem changes)
db9 onboard --dry-run
db9 onboard --print-locations

# Advanced: custom skill source
db9 onboard --skill-url https://db9.ai/skill.md
db9 onboard --skill-path ./SKILL.md
db9 onboard --force

Supported agents and default install locations:

Agent	--scope user	--scope project	Notes
codex	~/.codex/skills/db9/SKILL.md (or $CODEX_HOME/…)	—	Codex currently supports user scope only
claude	~/.claude/skills/db9/SKILL.md	./.claude/skills/db9/SKILL.md	--scope both installs both
opencode	~/.config/opencode/skills/db9/SKILL.md	./.opencode/skills/db9/SKILL.md	--scope both installs both
agents	~/.agents/skills/db9/SKILL.md	./.agents/skills/db9/SKILL.md	Generic agent-compatible directory

For agent workflow patterns, see Agent Workflows.

Related Docs

• TypeScript SDK — programmatic database management with get-db9
• SQL Reference — SQL engine compatibility and features
• Extensions — fs9, HTTP, vector, pg_cron, and more
• Connect — connection strings, TLS, and driver configuration