# DBX CLI > Use the native DBX CLI to read connections, schemas, query results, and AI context from terminals, scripts, CI, and Codex. Source: https://dbxio.com/en/docs/cli Language: en Relative links resolve against https://dbxio.com/en/docs/cli. DBX CLI is a dedicated command line package for terminal, script, and coding-agent workflows. It shares DBX connection storage and SQL safety rules with the MCP server. ## Install ### npm ```bash npm install -g @dbx-app/cli ``` ### Homebrew ```bash 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. ```bash 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: ```bash 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: ```bash 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 ` 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 ```bash 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: ```bash dbx doctor dbx doctor --json ``` If the optional platform package was not installed, reinstall without `--no-optional`: ```bash 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: ```bash 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: ```bash 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: ```bash 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. ```bash 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. ```bash 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: ```bash 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](/en/docs/mcp#stateful-query-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: ```bash dbx query local --json -- "-- comment select 1" ``` ## 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 | | `HOME_NOT_FOUND` | The default user skills directory cannot be resolved | | `SKILL_MODIFIED` | An unmanaged or locally edited DBX Skill was found | | `SKILL_PATH_UNSAFE` | A managed Skill path is a symbolic link | | `SKILL_READ_FAILED` | An installed Skill file could not be read | | `SKILL_WRITE_FAILED` | The bundled Skill could not be installed | | `ERROR` | Unexpected runtime failure | ## 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: ```bash open 'dbx://open' ``` A web button can link to the protocol directly: ```html Open in DBX ``` Use `dbx://connection/new` without an `id` to open the new connection dialog with connection fields prefilled. DSN mode: ```bash open 'dbx://connection/new?url=postgres%3A%2F%2Fapp%3Asecret%40db.internal%3A5432%2Forders' ``` Field mode: ```bash open 'dbx://connection/new?type=mysql&host=127.0.0.1&port=3306&user=root&password=secret&database=test' ``` Supported fields: | Field | Meaning | | ------------ | ---------------------------------------------------------------------------------------- | | `type` | Database type; service types include `etcd`, `consul`, `nacos-v2`, `nacos-v3`, `r-nacos` | | `url` | Database DSN; URL encoding is recommended | | `name` | Display name in DBX; when omitted, DBX uses `database`, then `host` | | `host` | Hostname or IP address | | `port` | Port | | `user` | Username | | `password` | Password | | `database` | Database name; for Redis this can be a DB index such as `0` | | `url_params` | Extra connection parameters, such as `sslmode=require` | | `ssl` | Enable SSL when set to `true` | | `one_time` | Automatically connect when set to `true`, then delete the connection after disconnecting | One-time connection example: ```bash 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: ```bash 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: ```bash 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: | Parameter | Update behavior | | ------------------------ | ----------------------------------------------------------------------------------- | | `name`, `host` | Replace the current value; empty values are rejected | | `port` | Replace the port with an integer from 1 to 65535 | | `user`, `password` | Prefill credentials without trimming whitespace; an empty value clears the field | | `database`, `url_params` | Replace the current value; an empty value clears the field | | `ssl` | Update the SSL switch; effective TLS behavior follows the driver and URL parameters | 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. Before testing system-level `dbx://` launches, install and open DBX Desktop once so the operating system can register the URL scheme. On macOS, use `open 'dbx://open'` or `open 'dbx://connection/new?...'` to test it. A deep link may expose a database password or Consul ACL token in browser and terminal history. Do not put credential-bearing links in shared logs, shell history, tickets, or chat messages. ## Codex Codex can call the CLI directly from shell tools: ```bash dbx schema describe local users --json dbx context local --tables users,orders | codex exec "Write a retention query" ```