CLI

Install

npm install -g @persql/cli
persql --help

Node 20 or newer. npx @persql/cli ... runs it without installing.

Sign in

persql login opens the web app in the browser (BROWSER=none prints the link instead), which shows the same code as the terminal. Approve it, and the terminal stays signed in for 30 days, renewed while it is in use. On a machine with no browser, persql login --key persql_... saves a developer key made under Account in the web app’s Settings instead. The sign-in is stored in ~/.config/persql/config.json (or under $XDG_CONFIG_HOME); PERSQL_KEY and PERSQL_API_URL in the environment override it, for example in a CI job.

Commands

Every command takes --json to print JSON instead of a table, and --help for its arguments. A <db> is a database’s id or its name.

Command	Usage	Does
login	persql login [--key persql_...] [--api https://api.persql.com]	Sign this terminal in through the browser, or save a developer key.
logout	persql logout	Forget the saved sign-in on this machine.
whoami	persql whoami	Who this terminal is signed in as.
dbs	persql dbs	List your databases.
create	persql create <name>	Make a new, empty database.
rename	persql rename <db> <name>	Rename a database.
drop	persql drop <db> --yes	Delete a database and everything in it.
tables	persql tables <db>	The tables of a database with their row counts.
schema	persql schema <db>	The schema of a database as SQL, or as JSON with --json.
query	persql query <db> <sql> [--param v]... [--all] [--csv] [--json]	Run one SQL statement; a SELECT prints rows. Pass - to read the SQL from stdin.
import	persql import <db> <file>...	Import files into a database: CSV, TSV, Excel, a SQL dump, a SQLite file, or a zip.
export	persql export <db> [--as sql|sqlite|csv] [--table t] [--out path]	Export a database as SQL or SQLite, or one table as CSV, to a file.
backups	persql backups <db>	The backups of a database.
backup	persql backup <db> [--label text]	Take a backup of a database, as a SQL file you can download and restore.
restore	persql restore <db> <backup-id> --yes	Restore a backup; the current state is backed up first.
mcp	persql mcp [--config]	Serve your databases to an agent over MCP on stdin/stdout; --config prints the client snippet.

Examples

persql create Ledger
persql import ledger expenses.csv                # any size; progress on stderr
persql query ledger "SELECT category, SUM(amount) FROM expenses GROUP BY 1"
persql query ledger "SELECT * FROM expenses WHERE day > ?" -p 2026-01-01 --all --csv > this-year.csv
echo "SELECT COUNT(*) FROM expenses" | persql query ledger -
persql backup ledger --label "before the clean-up"
persql export ledger --as sqlite -o ledger.sqlite
persql export ledger --table expenses -o expenses.csv
persql restore ledger backup_... --yes

Exit codes: 0 success, 1 the API refused the request or could not be reached, 2 the command was not understood.