---
title: DBX CLI
description: Use DBX connections 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
```

Requires Node.js 22.13.0 or newer.

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

```bash
pnpm rebuild better-sqlite3 keytar --pending
```

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

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

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:

```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 one SQL statement. It 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`.

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