CLI reference

npm i -g @persql/cli
persql login

persql login opens your default browser at https://console.persql.com/cli-auth?code=…. After you click Authorize, the CLI receives a psql_cli_… token and writes it to ~/.persql/config.json (mode 0600). On a headless machine, paste a token directly with persql login -t <token>.

CLI tokens are user-scoped (the row sits in the cli_token table, separate from namespace-scoped psql_live_… tokens) and bound to your user account. Revoke them in the console under Settings → CLI sessions (or persql logout to clear the local copy).

Commands

Auth

Command	What it does
persql login [-t <token>]	Browser device flow. -t skips the browser.
persql logout	Clear the saved token.
persql whoami	Show the logged-in user.

Namespaces

Command	What it does
persql ns list [--json]	List namespaces you belong to.
persql ns use <slug>	Set the default namespace (saved per machine).

Once a default namespace is set, <ref> arguments accept either <ns>/<slug> or just <slug>.

Databases

Command	What it does
persql db list [--ns <slug>] [--json]	List databases in a namespace.
persql db create [name] [--ns <slug>] [--slug <slug>] [--region <r>]	Create. --region accepts auto, wnam, enam, weur, eeur, apac.
persql db delete <ref> [-f]	Delete (with confirm prompt; -f skips).
persql db query <ref> "<sql>" [--json]	One-shot query. --json emits rows as JSON.
persql db shell <ref>	Interactive SQL shell. Supports .tables, .schema [name], .exit. End SQL with ; to run multi-line.
persql db export <ref> [--out <file>]	SQL dump (drop-in for sqlite3 .dump). Writes to stdout if --out is omitted.
persql db import <ref> <file>	Apply a SQL dump in one transaction.

Examples

# Set the default namespace, then refer to dbs by slug.
persql ns use acme
persql db list

# Create, query, dump.
persql db create orders --region weur
persql db query orders "SELECT count(*) FROM customers"
persql db export orders --out orders-snapshot.sql

# Interactive shell.
persql db shell orders
orders> SELECT id, email FROM customers LIMIT 5;
orders> .exit

# Headless seeding (CI, container).
persql login -t "$PERSQL_CLI_TOKEN"
persql db import orders ./seed.sql

Configuration

Config file: ~/.persql/config.json (or $XDG_CONFIG_HOME/persql/config.json if XDG_CONFIG_HOME is set). Mode 0600 — readable only by you.

Variable	Default	Purpose
PERSQL_API_URL	https://api.persql.com	API base URL
PERSQL_APP_URL	https://console.persql.com	Console URL used during persql login
PERSQL_TOKEN	—	Override the saved token for one invocation
XDG_CONFIG_HOME	~/.config	Honored when locating the config file

Exit codes

0 on success. 1 on any error. persql db query errors are printed to stderr with the API error message; exit code is 1.