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 browser to the console (BROWSER=none prints the link instead), which shows the same code the terminal does; approve it and the terminal is signed in for a month of use, longer while it keeps being used. On a machine with no browser, persql login --key persql_... saves a developer key from the console’s Account page instead. The sign-in lives in ~/.config/persql/config.json (or under $XDG_CONFIG_HOME); PERSQL_KEY and PERSQL_API_URL in the environment override it, which is what a CI job wants.

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]... [--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 dump you can download and restore.
restore	persql restore <db> <backup-id> --yes	Restore a backup; a backup of now is taken first.
notes	persql notes <db>	The notes on a database: what a table is for, what a column means.
note	persql note <db> <about> <text>	Add a note about a table or a column (table, or table.column).
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 --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 snap_... --yes

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