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
Watch filesystem changes in real time	Filesystem Watch below
Deploy serverless functions (experimental)	Functions 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

▶ Run

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

macOS prerequisite for db9 fs mount

db9 fs mount on macOS currently depends on the macFUSE kernel backend.

Terminal

brew install --cask macfuse

After installation, macOS may require manual system extension approval in System Settings > Privacy & Security before FUSE mounts are allowed.

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, csv, raw (CSV without headers), or quiet (minimal machine-readable)
--json	—	—	Shorthand for --output json
--quiet	—	—	Suppress non-essential output (only print machine-readable values)
--insecure	DB9_INSECURE	—	Skip TLS certificate verification
--experimental	DB9_EXPERIMENTAL	—	Enable experimental features (e.g. functions)
-d, --database <DB>	DB9_DATABASE	—	Override the default database for this command

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.

Adopt Anonymous Databases

Transfer databases created under an anonymous trial account into your verified account:

Terminal

db9 adopt

This launches an interactive flow that verifies ownership of the anonymous account (via anonymous_secret) and migrates selected databases into your current account. For details, see Anonymous & Claimed Databases.

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 --project <project_id>  # assign to a project
db9 create --name myapp --show-secrets   # print password & connection string

# List
db9 list

# List with database storage sizes
db9 list --size

# Filter by project
db9 list --project <project_id>

# Check login status
db9 status

# Show database status
db9 db status <db>

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

# Output connection as DATABASE_URL=... format (for .env files)
db9 db connect <db> --env

# 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.

Shorthand Aliases

Most db9 db <cmd> subcommands have top-level aliases so you can type less:

Shorthand	Equivalent
db9 sql <db>	db9 db sql <db>
db9 connect <db>	db9 db connect <db>
db9 inspect <db>	db9 db inspect <db>
db9 users <db>	db9 db users <db>
db9 seed <db>	db9 db seed <db>
db9 dump <db>	db9 db dump <db>
db9 cron <db>	db9 db cron <db>
db9 cat <db>:/path	Read a remote file
db9 rm <db>:/path	Remove a remote file
db9 mv <db>:/src <db>:/dst	Move/rename a remote file
db9 sh <db>	db9 fs sh <db>
db9 cp <src> <dst>	db9 fs cp <src> <dst>
db9 ls <db>:/path	db9 fs ls <db>:/path
db9 mount <db> <dir>	db9 fs mount <db> <dir>

The cat, rm, and mv shorthands operate on the database filesystem directly — no need for db9 fs sh.

Inspect and Observability

Subcommand	Description
db9 db inspect	Overview metrics dashboard
db9 db inspect queries	Query samples and performance
db9 db inspect report	Combined summary + queries report
db9 db inspect schemas	List database schemas
db9 db inspect tables	List database tables
db9 db inspect indexes	List database indexes
db9 db inspect slow-queries	Slow queries sorted by p99 latency

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 / --query), file (-f / --file), stdin, or an interactive REPL. The <db> argument is optional — if omitted, the CLI auto-selects the default database or prompts interactively.

The interactive REPL defaults to direct pgwire mode (faster, real PostgreSQL error messages) with automatic API fallback. Use --api to force HTTP API mode, or --direct / -D to explicitly request pgwire.

Terminal

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

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

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

# Interactive REPL (TTY only — defaults to direct pgwire)
db9 db sql <db>

# Force HTTP API mode (disables auto-direct in REPL)
db9 db sql <db> --api

# Explicit direct pgwire mode
db9 db sql <db> --direct
db9 db sql <db> --direct --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> --output-file ./backup.sql

Filesystem

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

Terminal

# List remote files and directories
db9 fs ls <db>:/path
db9 fs ls --long <db>:/path         # long format (permissions, size, mtime)
db9 fs ls --recursive <db>:/path    # recursive listing

# Interactive filesystem shell
db9 fs sh <db>

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

# Quick file operations (top-level shortcuts)
db9 cat <db>:/path/to/file              # Print file contents
db9 rm <db>:/path/to/file               # Remove a file
db9 mv <db>:/old/path <db>:/new/path    # Move or rename
db9 tailf <db>:/logs/app.log            # Follow remote file appends

# 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 --recursive ./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" --multipart-threshold 16777216  # 16 MB
db9 fs mount <db> "$HOME/mnt/mydb" -f            # foreground
db9 fs mount <db> "$HOME/mnt/mydb" --writeback   # async upload on close (faster, crash loses unsynced data)
db9 fs mount <db> "$HOME/mnt/mydb" --include '*.md'               # sync only .md files
db9 fs mount <db> "$HOME/mnt/mydb" --include '*.rs' --exclude 'target/**'
db9 fs mount <db> "$HOME/mnt/mydb" --no-ignore    # disable .fuseignore

Filesystem Watch

Monitor filesystem events in real time. The watch command polls the fs9_events() table function and streams changes as they happen.

Terminal

# Watch all events on a database
db9 fs watch <db>:/

# Watch events under a specific path
db9 fs watch <db>:/data/

# Poll every 5 seconds (default: 1)
db9 fs watch <db>:/ --interval 5

# Output JSON lines (for piping to other tools)
db9 fs watch <db>:/ --json

Supported event types: CREATE, WRITE, DELETE, RENAME, MKDIR. Events include the path, timestamp, file size, and (for renames) the old path.

Plain-text output example:

Output

10:23:45.123  CREATE   /data/file.txt
10:23:46.456  RENAME   /data/old.txt -> /data/new.txt
10:23:47.789  DELETE   /data/file.txt

If the internal event ring overflows (events arrive faster than the polling interval), the CLI prints a warning so you can increase the polling frequency or narrow the path prefix.

File Tail (follow)

Follow a remote file and print appended content, similar to tail -f:

Terminal

# Follow a log file (prints last 10 lines, then streams new content)
db9 fs tailf <db>:/logs/app.log

# Show last 50 lines before following
db9 fs tailf <db>:/logs/app.log --lines 50

# Custom polling interval (default: 1 second)
db9 fs tailf <db>:/logs/app.log --interval 2

Tee (stdin to remote file)

Read stdin, echo it to stdout, and write it to a remote file — like Unix tee but targeting the database filesystem:

Terminal

# Pipe command output to a remote file
echo "hello" | db9 fs tee <db>:/logs/out.txt

# Append instead of overwriting
cat local.txt | db9 fs tee -a <db>:/logs/out.txt

Flag	Default	Description
-a, --append	off	Append to the file instead of overwriting

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

Filesystem Shell Builtins

The interactive shell (db9 fs sh) supports a POSIX-like command set:

Category	Commands
File ops	ls, cat, cp, mv, rm, touch, mkdir, stat, find, tree, diff, patch
Text processing	grep, head, tail, sort, uniq, cut, wc, tr, rev, tee, jq
Navigation	cd, pwd, basename, dirname
Shell	echo, printf, read, export, set, test, alias, source, env, date, sleep, seq
Control flow	if/then/fi, for/do/done, while/do/done, case/esac, pipes, redirections

Use help <command> inside the shell for per-command usage.

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    # print password + connection string
db9 branch create <db> --name feature1 --show-password   # print password only
db9 branch create <db> --name feature1 --show-connection-string  # print connection string only

# Point-in-time branch (PITR) — branch from a specific past timestamp
db9 branch create <db> --name rollback --snapshot-at 2026-03-22T06:00:00Z

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

# Delete a branch database
db9 branch delete <branch_db>

The --snapshot-at flag accepts an RFC 3339 UTC timestamp (e.g. 2026-03-22T06:00:00Z). When TiKV snapshot restore is available, the branch will contain the parent’s data as of that timestamp rather than the current state.

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.

Subcommand	Description
db9 db cron list	List all cron jobs
db9 db cron create	Create a cron job
db9 db cron delete	Delete a job by ID or name
db9 db cron history	Show job execution history
db9 db cron enable	Enable a disabled job
db9 db cron disable	Disable a job
db9 db cron status	Show job status

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 --job <job_id_or_name> --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.

Functions

Serverless functions let you deploy and run JavaScript/TypeScript code that executes against your database.

Subcommand	Description
db9 functions list	List functions in a database
db9 functions create	Create a new function
db9 functions update	Update an existing function by name or ID
db9 functions invoke	Invoke a function
db9 functions history	List recent runs, or show details of a specific run
db9 functions logs	Show logs for a specific run
db9 functions secrets list	List all secrets (names only)
db9 functions secrets set	Create or update a secret
db9 functions secrets delete	Delete a secret

Terminal

# List functions
db9 functions list --db myapp

# Create a function (reads index.js or main.ts from current directory)
db9 functions create my-func --db myapp

# Create with TypeScript source
db9 functions create my-func --db myapp --ts

# Create with execution limits
db9 functions create my-func --db myapp \
  --limits-json '{"timeout_ms":60000,"memory_mb":128}'
db9 functions create my-func --db myapp --limits-file ./limits.json
db9 functions create my-func --db myapp --timeout 30000

# Bind secrets to a function
db9 functions create my-func --db myapp --secret API_KEY=my_api_key

# Grant filesystem access to a function
db9 functions create my-func --db myapp --fs9-scope /data:ro --fs9-scope /output:rw

# Create a public function (callable via publishable key)
db9 functions create my-func --db myapp --visibility public

# Update an existing function
db9 functions update my-func --db myapp -f ./updated.js
db9 functions update my-func --db myapp --timeout 60000 --secret NEW_KEY=my_new_key
db9 functions update my-func --db myapp --visibility private

# Invoke a function
db9 functions invoke my-func --db myapp
db9 functions invoke my-func --db myapp --payload '{"key":"value"}'

# View run history and logs
db9 functions history my-func --db myapp -n 50
db9 functions history my-func <run_id> --db myapp
db9 functions logs my-func <run_id> --db myapp

# Manage secrets
db9 functions secrets list --db myapp
db9 functions secrets set MY_SECRET --db myapp --value "secret-value"
db9 functions secrets set MY_SECRET --db myapp --value-stdin
db9 functions secrets delete MY_SECRET --db myapp

The --db flag is optional when a default database is set via db9 use. The --timeout convenience flag overrides any timeout_ms value in the limits JSON.

Sharing

db9 share is a shorthand for creating a database-scoped token. It creates the token and prints a ready-to-use connection string.

Terminal

# Read-only share (default), 7-day expiry
db9 share my-app

# Read-write share
db9 share my-app --rw

# Custom expiry (30 days)
db9 share my-app --expires 30

# Custom token name
db9 share my-app --name team-token

Flag	Default	Description
--rw	off	Grant read-write access (default: read-only)
--expires <days>	7	Token expiry in days
--name <name>	share-<db>-YYYYMMDD	Custom token name

Under the hood this calls POST /customer/tokens with the appropriate scope_json. For more control (multi-database scopes, custom names), use db9 token create --scope.

Explorer

db9 explore launches a browser-based file and SQL explorer. It downloads a pre-built SPA to ~/.db9/explorer/ and serves it locally with API proxying.

Terminal

# Open explorer for a database
db9 explore mydb

# Custom port
db9 explore mydb --port 8080

# Don't auto-open the browser
db9 explore mydb --no-open

# Use cached assets without checking for updates
db9 explore --no-download

# Force re-download even if cached
db9 explore mydb --force-download

Flag	Default	Description
--port <port>	7979	Local port (env: DB9_EXPLORER_PORT)
--no-open	off	Skip automatic browser open
--no-download	off	Use cached assets, skip update check
--force-download	off	Re-download assets even if cached

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

# Create a database-scoped token (read-only or read-write)
db9 token create --name readonly-token --scope mydb:ro
db9 token create --name multi-db --scope app:rw --scope analytics:ro

# 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.

Error Messages

Common errors and how to resolve them.

Error	Cause	Resolution
not authenticated	No token found in ~/.db9/credentials	Run db9 login or set DB9_API_KEY env var
database not found	Wrong name/ID, or database was deleted	Run db9 list to see available databases
permission denied	Token lacks the required scope	Create a new token: db9 token create
connection refused	API endpoint unreachable	Check network; verify --api-url flag or DB9_API_URL env var
rate limit exceeded	Too many requests in a short window	Wait and retry; implement exponential backoff in scripts
name already exists	Duplicate database name	Choose a different name, or delete the existing database first
invalid token	Token has expired or been revoked	Run db9 login or create a new token
database is not active	Database is in CREATING, CLONING, or DISABLED state	Check state with db9 status <name>; wait for ACTIVE
no databases found	Account has no databases yet	Run db9 create --name <name> to create one
WebSocket connection failed	Filesystem (fs9) WebSocket unavailable	Verify the database is active; check fs_websocket_url with db9 status <name>

Exit Codes

db9 follows standard Unix exit code conventions for use in shell scripts and CI/CD pipelines.

Code	Meaning	Example trigger
0	Success	Command completed without errors
1	Error	Any failure — see stderr for details

Usage in shell scripts:

Terminal

db9 create --name mydb
if [ $? -ne 0 ]; then
  echo "Database creation failed" >&2
  exit 1
fi

# Or inline
db9 create --name mydb || { echo "Failed"; exit 1; }

Capturing error output:

Terminal

output=$(db9 db sql mydb -q "SELECT 1" 2>&1)
if [ $? -ne 0 ]; then
  echo "Error: $output" >&2
  exit 1
fi

Troubleshooting

Authentication failures

Symptom: not authenticated or invalid token errors.

Terminal

# Check current auth status
db9 status

# Re-authenticate interactively
db9 login

# Use an API key directly (CI/CD)
export DB9_API_KEY=your-token
db9 list

# View the credentials file
cat ~/.db9/credentials

# List all tokens
db9 token list

Network errors and connection refused

Symptom: connection refused or timeouts when running any command.

Terminal

# Check which API endpoint is configured
db9 status

# Override the API URL for a single command
db9 --api-url https://api.db9.ai list

# Set permanently via environment
export DB9_API_URL=https://api.db9.ai

If behind a corporate proxy, ensure HTTPS_PROXY or https_proxy is set in your environment before running db9 commands.

Permission denied

Symptom: Commands fail with permission denied after authentication succeeds.

API tokens can be created with limited scopes. Create a new full-access token and switch to it:

Terminal

db9 token create --name full-access
export DB9_API_KEY=<new-token>

Database stuck in non-ACTIVE state

Symptom: database is not active when running SQL or filesystem commands.

Terminal

# Check current state
db9 db status mydb

States and meanings:

State	Description
CREATING	Initial provisioning in progress (usually < 30s)
CLONING	Branch copy in progress
ACTIVE	Ready for connections
DISABLING	Deletion in progress
DISABLED	Deleted or suspended
CREATE_FAILED	Provisioning failed — delete and recreate

For branch databases, poll until active:

Terminal

while [ "$(db9 db status mydb --output raw 2>/dev/null)" != "ACTIVE" ]; do
  echo "Waiting for ACTIVE state…"
  sleep 2
done

Filesystem (fs9) WebSocket errors

Symptom: WebSocket connection failed when using db9 fs commands.

Terminal

# Verify the database is ACTIVE
db9 status mydb

# Check the WebSocket URL is present
db9 status mydb --json | jq .fs_websocket_url

If using the TypeScript SDK on Node.js 18–20, install the ws package:

Terminal

npm install ws

Then pass it as the WebSocket option when creating the client — see Filesystem (client.fs).

Verbose debug output

Set DB9_DEBUG=1 to enable verbose logging for any command:

Terminal

DB9_DEBUG=1 db9 list
DB9_DEBUG=1 db9 db sql mydb "SELECT 1"

Next Steps

• TypeScript SDK — Server-side database management with get-db9
• Browser SDK — Client-side data access with @db9/browser
• SQL Reference — SQL engine compatibility and features
• Extensions — fs9, HTTP, vector, pg_cron, and more
• Connect — Connection strings, TLS, and driver configuration