dbx/docs/content/docs/cli.mdx

---
title: DBX CLI
description: Use the native DBX CLI to read connections, schemas, query results, and AI context from terminals, scripts, CI, and Codex.
---

<Callout type="info">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.</Callout>

## Install

### npm

```bash
npm install -g @dbx-app/cli
```

### Homebrew

```bash
brew tap t8y2/dbx
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
```

## Common Commands

```bash
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:

```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                   |
| `ERROR`                  | Unexpected runtime failure                          |

## 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:

```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, such as `mysql`, `postgres`, `redis`, or `mongodb`                        |
| `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'
```

<Callout type="info">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://connection/new?...'` to test it.</Callout>

## 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"
```