DBX CLI

Command line interface for DBX database connections, schema inspection, safe queries, and prompt-ready schema context.

Install

npm install -g @dbx-app/cli

Requires Node.js 22.13.0 or newer.

Usage

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

Commands

| Command | Description | |---|---| | dbx doctor | Show local DBX config and desktop bridge diagnostics | | dbx capabilities | Show direct-query and desktop-bridge database support | | dbx connections list | List DBX connections without printing secrets | | dbx schema list <connection> | List tables and views | | dbx schema describe <connection> <table> | Show table columns | | dbx query <connection> <sql> | Execute one SQL statement | | dbx query <connection> --file ./query.sql | Execute SQL from a file | | dbx context <connection> | Print compact schema context for prompts | | dbx open <connection> <table> | Open a table in DBX Desktop |

Output

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.

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

Query Controls

dbx query is read-only by default.

Use --limit <n> to control returned query rows and --timeout <duration> to control query timeout. Durations accept ms, s, or m, such as 500ms, 10s, or 1m.

Use --allow-writes for non-dangerous write statements. Dangerous SQL such as DROP, TRUNCATE, and ALTER requires both --allow-writes and --allow-dangerous-sql.

For SQL that starts with a dash, pass -- before the SQL:

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

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

Desktop App Requirements

Some CLI commands can run without DBX Desktop:

• connections list
• schema list
• schema describe
• query
• context

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.

Use dbx doctor to check whether the DBX connection database, connection table, native SQLite loader, and desktop bridge are available. Use dbx capabilities to list direct-query and bridge-required database types.

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

Error Codes

CLI JSON errors use stable codes:

| Code | Meaning | |---|---| | UNKNOWN_OPTION | An unsupported flag was provided | | INVALID_OPTION | A flag is missing a value or has an invalid value | | INVALID_ARGUMENT | Positional arguments are missing or conflicting | | CONNECTION_STORE_ERROR | DBX connection storage exists but could not be read | | CONNECTION_NOT_FOUND | No DBX connection matched the requested name | | SQL_BLOCKED | SQL safety rules blocked execution | | DBX_NOT_RUNNING | DBX Desktop bridge is unavailable | | ERROR | Unexpected runtime failure |

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"