DBX CLI

安装

npm

npm install -g @dbx-app/cli

Homebrew

brew tap t8y2/tap
brew install dbx-cli

通过 npm 安装时需要 Node.js 18.18.0 或更高版本。CLI 本身不依赖 better-sqlite3，也不受 Node.js native module ABI 影响。Homebrew 用户不需要单独管理 Node.js。

独立原生版本

packages-v* GitHub Release 会提供适用于 macOS、Linux 和 Windows 的 CLI 原生压缩包。下载对应平台的压缩包后，使用 CLI-SHA256SUMS 校验，解压即可直接运行 dbx，不需要 Node.js。

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

如果使用自定义或便携版 DBX 数据目录，可以设置 DBX_DATA_DIR。

查看版本：

dbx --version

官方 Agent Skill

CLI 二进制内置了供 Codex、Claude Code 等可执行 Shell 的 AI Agent 使用的官方 DBX Skill。安装或升级 CLI 后启用一次：

dbx agent setup
dbx agent status

默认安装到 ~/.agents/skills/dbx。setup 全程离线运行，可重复执行并升级到 CLI 内置的新版本；如果目标位置存在非 DBX 管理或经过本地修改的 Skill，则不会覆盖，除非显式使用 --force。Agent 使用其它 Skill 根目录时可传入 --skills-dir <路径>。

Skill 负责告诉 AI 何时以及如何安全调用 CLI，并不会绕过 CLI、连接或数据库本身的权限限制。普通用户仍然可以直接运行所有 dbx 命令。

常用命令

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

诊断

使用 dbx doctor 查看本地 DBX 路径、连接存储健康状态，以及桌面端 bridge 是否可用：

dbx doctor
dbx doctor --json

如果 npm 没有安装当前平台包，请不要使用 --no-optional，重新安装：

npm uninstall -g @dbx-app/cli
npm install -g @dbx-app/cli

使用 dbx capabilities 查看哪些数据库类型可以直接查询，哪些当前需要 DBX 桌面端：

dbx capabilities
dbx capabilities --json

当前原生直连清单由 CLI 二进制维护，包括 PostgreSQL、Redshift、MySQL、Doris、StarRocks、Manticore Search、SQLite、rqlite、KWDB 和 QuestDB。dbx capabilities 是当前版本的权威输出；其他类型需要运行中的 DBX Desktop bridge 或对应 Agent/外部驱动基础设施。

执行模式

本地存储

默认情况下 CLI 读取与 Desktop/MCP 相同的 dbx.db 连接存储。设置 DBX_DATA_DIR 时应指向包含 dbx.db 的目录。

• 原生直连类型可以在 Desktop 关闭时查询
• bridge 类型需要 Desktop 正在运行，并能从数据目录中的 bridge 端口文件发现本地服务
• Agent/JDBC、DuckDB 和其它外部驱动路径仍需要在 DBX 中安装匹配组件
• dbx open 始终是 Desktop UI 操作，Desktop 未运行时返回 DBX_NOT_RUNNING

DBX Web / Docker

设置 DBX_WEB_URL 后，CLI 改为使用部署的 DBX Web 后端，而不是读取本机连接存储：

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

DBX_WEB_PASSWORD 是 Web 登录密码。Web 模式中的连接、权限、驱动和文件路径都属于服务器环境；dbx open 仍需要本机 Desktop bridge，不应作为远程 Web 自动化入口。

默认连接

设置 DBX_CONNECTION 后，query 和 context 命令可以省略连接名：

DBX_CONNECTION=local dbx query "select 1" --json
DBX_CONNECTION=local dbx context --tables users,orders

输出格式

使用 --json 或 --format json 可以获得稳定的机器可读输出。--format csv 适合把查询、连接、Schema 数据传给其它命令行工具。

dbx query local "select id, name from users" --format csv

错误会写入 stderr，并返回非零退出码。

查询控制

dbx query 对 SQL 连接执行一条 SQL，对 MongoDB 连接接受受支持的 Mongo shell 命令。Redis 不通过这个命令执行，需使用 MCP Redis 工具或 DBX 专用工作区。默认只读。

dbx query local "select * from users" --limit 50 --timeout 10s --json

时间支持 ms、s、m，例如 500ms、10s、1m。

非危险写操作需要显式使用 --allow-writes：

dbx query local "update users set name = 'Ada' where id = 1" --allow-writes

DROP、TRUNCATE、ALTER 等危险 SQL 需要同时显式使用 --allow-writes 和 --allow-dangerous-sql。显式事务语句仍会被 CLI 阻止；需要多步固定 Session 时使用 MCP 有状态会话 或 DBX 编辑器。

生产数据库上的写入和 DDL 即使传入两个允许参数也会被阻止。CLI 使用连接/数据库生产识别、SQL 风险分类、连接只读保护和数据库权限形成多层边界；允许参数不是绕过生产保护的开关。

以短横线开头的 SQL

如果 SQL 以短横线开头，在 SQL 前加 --：

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

错误码

CLI JSON 错误使用稳定错误码：

桌面端 Deep Link

DBX 桌面端支持通过 Deep Link 从浏览器、堡垒机或脚本唤起客户端。

仅启动或聚焦 DBX，不打开其他窗口：

open 'dbx://open'

网页按钮可以直接使用：

<a href="dbx://open">使用 DBX 打开</a>

使用不带 id 的 dbx://connection/new 可以打开新建连接窗口并预填连接信息。

DSN 模式：

open 'dbx://connection/new?url=postgres%3A%2F%2Fapp%3Asecret%40db.internal%3A5432%2Forders'

字段模式：

open 'dbx://connection/new?type=mysql&host=127.0.0.1&port=3306&user=root&password=secret&database=test'

支持的字段：

一次性连接示例：

open 'dbx://connection/new?type=redis&host=127.0.0.1&port=6379&user=default&password=secret&database=0&one_time=true'

Nacos 与服务注册中心示例：

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 是 nacos-v2 的别名，rnacos 是 r-nacos 的别名。URL 模式会保留服务端点路径，顶层 host、port、user、password、ssl 会覆盖 url 中的对应值。Consul 的 password 表示 ACL token；Nacos 传入 password 时必须同时传入 user。省略 v 或使用 v=1 表示当前深链协议，其他版本会被拒绝。

按 ID 更新已保存连接

在同一个 dbx://connection/new 路由上增加 id，即可打开指定的已保存连接进行编辑。例如，堡垒机可以为已有连接传入新的登录凭据：

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

将 saved-connection-id 替换为 MCP 工具 dbx_list_connections 返回的连接 ID。更新按 ID 精确匹配，不按显示名称查找。CLI 命令 dbx connections list --json 目前只列出名称和端点等信息，不返回连接 ID。

收到更新链接后，DBX 只打开预填好的编辑窗口。检查修改内容并点击保存后，才会以原连接 ID 和原侧栏分组持久化修改。链接不会自动保存、测试或连接数据库；取消编辑不会修改已保存配置。ID 为空或不存在、目标是一次性连接、已有其他连接窗口打开时，更新会被拒绝，不会退回新建连接。

更新支持使用内置 MySQL、PostgreSQL、SQL Server 配置的已保存字段式连接；存在非空 connection_string 的连接不支持此更新流程。只有链接中明确提供的字段才会修改：

省略的字段保留原值，包括端口和 SSL 设置。需要清空字段时，保留参数名并传空值，例如 database=&url_params=。参数值应进行 URL 编码，例如密码中的字面量 + 应编码为 %2B。

保存时仍遵循现有的凭据清理规则和该连接的“保存密码”设置。

除 id 和上述字段外，只接受可选的协议版本 v=1。更新链接不接受 type、url、one_time（包括 one_time=false）、未知参数或重复参数名，也不能更改驱动配置或要求自动操作。

保存新的 SSO 凭据不会延长其有效期。MCP 可以读取保存后的连接配置，但仍会独立建立数据库会话，需要凭据仍然有效；更新不会把桌面端正在使用的会话转交给 MCP。

Codex

Codex 可以直接通过 shell 调用 CLI：

dbx schema describe local users --json
dbx context local --tables users,orders | codex exec "Write a retention query"