DBX CLI

Install

npm

npm install -g @dbx-app/cli

Homebrew

brew tap t8y2/tap
brew install dbx-cli

Node.js 18.18.0 or newer is required for the npm launcher. The CLI itself does not depend on better-sqlite3 or a Node.js native-module ABI. Homebrew users do not need to manage Node.js separately.

Standalone native binary

The packages-v* GitHub Release provides native CLI archives for macOS, Linux, and Windows. Download the archive matching your platform, verify it with CLI-SHA256SUMS, extract it, and run dbx directly. Standalone binaries do not require Node.js.

tar -xzf dbx-cli-linux-x64-gnu.tar.gz
chmod +x dbx
./dbx --version

Set DBX_DATA_DIR when using a custom or portable DBX data directory.

Check the installed version:

dbx --version

Official Agent Skill

The CLI binary includes the official DBX Skill for Codex, Claude Code, and other shell-capable AI agents. Enable it once after installing or upgrading the CLI:

dbx agent setup
dbx agent status

The default destination is ~/.agents/skills/dbx. setup runs entirely offline and can be repeated to upgrade to the version bundled with the CLI. It refuses to replace an unmanaged or locally modified Skill unless --force is supplied. Pass --skills-dir <path> when an agent reads a different skills root.

The Skill teaches the AI when and how to call the CLI safely. It does not bypass CLI, connection, or database permissions, and people can continue to run every dbx command directly.

Common Commands

dbx doctor
dbx capabilities
dbx agent setup
dbx agent status --json
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 the optional platform package was not installed, reinstall without --no-optional:

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

The CLI binary currently lists PostgreSQL, Redshift, MySQL, Doris, StarRocks, Manticore Search, SQLite, rqlite, KWDB, and QuestDB as direct-query types. dbx capabilities is authoritative for the installed version. Other types require a running DBX Desktop bridge or their Agent/external-driver infrastructure.

Execution Modes

Local Storage

By default, CLI reads the same dbx.db connection store used by Desktop and MCP. DBX_DATA_DIR must point to the directory containing dbx.db.

• Direct-query types can run while Desktop is closed
• Bridge types require Desktop to be running and discoverable through the bridge port file in the data directory
• Agent/JDBC, DuckDB, and other external-driver paths still require matching components installed through DBX
• dbx open is always a Desktop UI operation and returns DBX_NOT_RUNNING when the app is unavailable

DBX Web and Docker

Set DBX_WEB_URL to use a deployed DBX Web backend instead of local connection storage:

DBX_WEB_URL=https://dbx.example.com \
DBX_WEB_PASSWORD='your-login-password' \
dbx connections list --json

DBX_WEB_PASSWORD is the Web login password. In Web mode, connections, permissions, drivers, and file paths belong to the server environment. dbx open still targets a local Desktop bridge and should not be treated as a remote Web automation API.

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 SQL for SQL connections and accepts supported Mongo shell commands for MongoDB connections. Redis is not executed through this command; use the MCP Redis tool or the DBX workspace instead. Query mode 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. Explicit transaction statements remain blocked by CLI; use MCP stateful sessions or the DBX editor for pinned multi-step sessions.

Writes and DDL against production databases remain blocked even when both flags are present. Production detection, SQL risk classification, connection read-only protection, and database privileges form independent upper bounds; the flags are not a production bypass.

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 deep links for launching the client from browsers, bastion hosts, or scripts.

Launch or focus DBX without opening another dialog:

open 'dbx://open'

A web button can link to the protocol directly:

<a href="dbx://open">Open in DBX</a>

Use dbx://connection/new without an id to open the new connection dialog 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'

Nacos and service-registry examples:

open 'dbx://connection/new?type=consul&host=127.0.0.1&port=8500&password=acl-token'
open 'dbx://connection/new?type=nacos-v3&host=127.0.0.1&port=8848&user=nacos&password=secret'
open 'dbx://connection/new?type=r-nacos&url=http%3A%2F%2F127.0.0.1%3A8848%2Fnacos&user=admin&password=secret'

nacos is an alias for nacos-v2, and rnacos is an alias for r-nacos. In URL mode, service endpoint paths are preserved; top-level host, port, user, password, and ssl fields override values from url. For Consul, password is the ACL token. Nacos requires user when password is present. Omitting v or using v=1 selects the current deep-link protocol; other versions are rejected.

Update a saved connection by ID

Add id to the same dbx://connection/new route to open an existing saved connection for editing. For example, a bastion host can provide fresh credentials for a saved connection:

open 'dbx://connection/new?id=saved-connection-id&user=fresh-sso-token&password=fresh-sso-token'

Replace saved-connection-id with the connection ID returned by the MCP dbx_list_connections tool. Matching uses the ID, never the display name. The CLI command dbx connections list --json currently lists names and endpoints but does not return connection IDs.

Receiving an update link only opens a prefilled edit dialog. Review the changes and click Save to persist them under the same connection ID and sidebar group. The link does not automatically save, test, or connect to the database. Canceling leaves the saved connection unchanged. An update is rejected if the ID is empty or unknown, the target is a one-time connection, or another connection dialog is already open; it never falls back to creating a connection.

Updates support saved, field-based connections using the built-in MySQL, PostgreSQL, or SQL Server profile. Connections with a nonempty connection_string are not supported by this update flow. Only explicitly supplied fields change:

Omitted fields retain their saved values, including port and SSL settings. To clear a field, include the parameter with an empty value, such as database=&url_params=. URL-encode parameter values; for example, use %2B for a literal + in a password.

The usual Save behavior still applies, including credential sanitization and the connection’s Save password setting.

Besides id and the fields above, only the optional protocol version v=1 is accepted. Update links reject type, url, one_time (including one_time=false), unknown parameters, and duplicate parameter keys. They cannot change the driver profile or request automatic actions.

Saving a refreshed SSO credential does not extend its lifetime. MCP can discover the saved profile, but it establishes its own database session and still needs a valid credential; the update does not transfer the desktop's active session to MCP.

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"