DBX CLI

Install

npm

npm install -g @dbx-app/cli

Homebrew

brew tap t8y2/dbx
brew install dbx-cli

Requires Node.js 22.13.0 or newer.

Check the installed version:

dbx --version

Common Commands

dbx doctor
dbx capabilities
dbx connections list --json
dbx connections list --format csv
dbx schema list local --json
dbx schema describe local users --json
dbx query local "select count(*) as total from users" --json
dbx query local "select id, name from users" --format csv
dbx query local "select * from users" --limit 50 --timeout 10s --json
dbx query local --file ./query.sql --json
dbx context local --tables users,orders
dbx open local users

Diagnostics

Use dbx doctor to inspect local DBX paths, connection-store health, and whether the desktop bridge is available:

dbx doctor
dbx doctor --json

If dbx doctor reports a NODE_MODULE_VERSION mismatch after switching Node.js versions, rebuild the native dependencies with the Node.js version you use to run dbx:

pnpm rebuild better-sqlite3 keytar --pending

For global npm installs, reinstall the CLI with the same Node.js version:

npm uninstall -g @dbx-app/cli
npm install -g @dbx-app/cli

Use dbx capabilities to see which database types can be queried directly and which currently require DBX Desktop:

dbx capabilities
dbx capabilities --json

Direct execution currently supports PostgreSQL/Redshift, MySQL-compatible databases (MySQL, Doris, StarRocks), and SQLite. Other database types use the DBX Desktop bridge until their drivers are added to @dbx-app/node-core.

Default Connection

Set DBX_CONNECTION to omit the connection name for query and context commands:

DBX_CONNECTION=local dbx query "select 1" --json
DBX_CONNECTION=local dbx context --tables users,orders

Output Formats

Use --json or --format json for stable machine-readable output. Use --format csv for query, connection, and schema data that should be piped into other command line tools.

dbx query local "select id, name from users" --format csv

Errors are written to stderr and return a non-zero exit code.

Query Controls

dbx query executes one SQL statement. It is read-only by default.

dbx query local "select * from users" --limit 50 --timeout 10s --json

Durations accept ms, s, or m, such as 500ms, 10s, or 1m.

Use --allow-writes for non-dangerous write statements:

dbx query local "update users set name = 'Ada' where id = 1" --allow-writes

Dangerous SQL such as DROP, TRUNCATE, and ALTER requires both --allow-writes and --allow-dangerous-sql.

SQL Starting With a Dash

Pass -- before SQL that starts with a dash:

dbx query local --json -- "-- comment
select 1"

Error Codes

CLI JSON errors use stable codes:

Desktop Deep Links

DBX Desktop supports dbx://connection/new links for opening the new connection dialog from browsers, bastion hosts, or scripts with connection fields prefilled.

DSN mode:

open 'dbx://connection/new?url=postgres%3A%2F%2Fapp%3Asecret%40db.internal%3A5432%2Forders'

Field mode:

open 'dbx://connection/new?type=mysql&host=127.0.0.1&port=3306&user=root&password=secret&database=test'

Supported fields:

One-time connection example:

open 'dbx://connection/new?type=redis&host=127.0.0.1&port=6379&user=default&password=secret&database=0&one_time=true'

Codex

Codex can call the CLI directly from shell tools:

dbx schema describe local users --json
dbx context local --tables users,orders | codex exec "Write a retention query"