# @dbx-app/cli 中文文档

规范地址：https://npmcn.com/package/%40dbx-app/cli/

版本：0\.4\.142
npm 元数据更新时间：2026-11-11T04:06:42.639Z
中文译文更新时间：2026-11-11T18:28:23.292Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dbx-app/cli
原文对照：https://npmcn.com/package/%40dbx-app/cli/?lang=original
项目主页：https://github.com/t8y2/dbx/tree/main/packages/cli
源码仓库：https://github.com/t8y2/dbx

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：20.9 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.18\.0
- 运行依赖：0 个
- 首次发布：2026-05-17T17:40:13.505Z
- 最新版本发布：2026-11-11T04:06:42.166Z
- 近 30 天下载量：5192（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：134（近 12 个月 134 个）

## 中文简介

DBX 数据库连接、 计划和安全查询的命令行接口

## 安装

```sh
npm install @dbx-app/cli
```

也可以使用：`pnpm add @dbx-app/cli`、`yarn add @dbx-app/cli`、`bun add @dbx-app/cli`

## README

# DBX 缩写

DBX数据库连接,计划检查,安全查询,以及快速准备的计划上下文的命令行接口.

## 安装

### 无

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

### 土生土长

```bash
brew tap t8y2/tap
brew install dbx-cli
```

Npm包为当前平台自动安装了本地CLI. 节点.js 18.1.8.0或更新型仅需要npm发射器;直接的本土分布不需要node.js.

### 原生下载

这个 `packages-v*` GitHub Release还提供了独立的本地CLI档案:

| 平台 | 存档 |
| --- | --- |
| macOS 苹果硅 | `dbx-cli-darwin-arm64.tar.gz` |
| macOS 英特尔 | `dbx-cli-darwin-x64.tar.gz` |
| Linux glibc ARM64 软件 | `dbx-cli-linux-arm64-gnu.tar.gz` |
| Linux glibc x64 (法语) | `dbx-cli-linux-x64-gnu.tar.gz` |
| 窗口 ARM64 | `dbx-cli-win32-arm64.zip` |
| 视窗 x64 | `dbx-cli-win32-x64.zip` |

验证已下载的归档 `CLI-SHA256SUMS`,取出,并直接运行本地二进制:

```bash
tar -xzf dbx-cli-linux-x64-gnu.tar.gz
chmod +x dbx
./dbx --version
./dbx connections list --json
```

独立的二进制不需要Node.js. 他们读取与桌面应用程序相同的 DBX 连接存储; set `DBX_DATA_DIR` 当使用自定义或便携式数据目录时.

## 正式探员Skill

CLI 二进制包括官方DBX Skill用于贝壳能AI代理. 在安装或升级CLI后启用一次 :

```bash
dbx agent setup
dbx agent status
```

默认位置是 `~/.agents/skills/dbx`。 。 。 . `setup` 运行完全离线,并可以重复安装更新的捆绑版本. 它拒绝覆盖一个未经管理或本地修改的DBX Skill, 除非 `--force` 提供。 使用 `--skills-dir <path>` 当代理读取不同的技能根.

## 使用量

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

## 图标

| 命令 | 说明 |
| --- | --- |
| `dbx doctor` | 显示本地 DBX 配置和桌面桥诊断 |
| `dbx capabilities` | 显示直流和桌面桥数据库支持 |
| `dbx agent setup` | 安装或更新捆绑的官方 DBX 技能 |
| `dbx agent status` | 检查已安装的 DBX 技能 |
| `dbx connections list` | 列出不打印机密的 DBX 连接 |
| `dbx schema list <connection>` | 列表表格和视图 |
| `dbx schema describe <connection> <table>` | 显示表格列 |
| `dbx query <connection> <sql>` | 执行一个 SQL 语句 |
| `dbx query <connection> --file ./query.sql` | 从文件中执行 SQL |
| `dbx context <connection>` | 打印急件的压缩上下文 |
| `dbx open <connection> <table>` | 在 DBX 桌面中打开一个表格 |

## 产出

使用 `--json` 或者说 `--format json` 用于稳定的机器可读输出。 使用 `--format csv` 用于查询、连接和计划数据,这些数据应被管道输入其他命令行工具.

错误写入为 stderr 并返回一个非零退出代码 .

## 查询控制

`dbx query` 默认情况下只读.

使用 `--limit <n>` 以控制返回的查询行和 `--timeout <duration>` 以控制查询超时。 接受期限 `ms`, (中文(简体) ), `s`,或 `m`,例如 `500ms`, (中文(简体) ), `10s`,或 `1m`。 。 。 .

使用 `--allow-writes` 对于非危险 写声明。 危险 SQL 如 `DROP`, (中文(简体) ), `TRUNCATE`,以及 `ALTER` 需要两者 `--allow-writes` 财务报告和审定财务报表 `--allow-dangerous-sql`。 。 。 .

对于SQL,从破折号开始,通过 `--` 在 SQL 之前 :

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

## 默认连接

设定 `DBX_CONNECTION` 以省略查询和上下文命令的连接名称:

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

## 桌面应用程序要求

一些 CLI 命令可以在没有 DBX 桌面的情况下运行 :

-   `connections list`
-   `schema list`
-   `schema describe`
-   `query`
-   `context`

直接执行支持PostgreSQL/Redshift,MySQL相容的数据库(MySQL,多丽丝,StarRocks)和SQLite. 其他数据库类型使用DBX桌面桥或DBX Agent/JDBC基础设施.

使用 `dbx doctor` 以检查是否有 DBX 连接数据库、连接表、本地 SQLite 加载器和桌面桥。 使用 `dbx capabilities` 以列出直流和桥接数据库类型.

如果未安装可选平台软件包,则无需安装即可重新安装 `--no-optional`数字 :

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

本地CLI不要求 `better-sqlite3` 而不是与节点js ABI结合.

## 错误代码

CLI JSON错误使用稳定代码 :

| 代码 | 含义 |
| --- | --- |
| `UNKNOWN_OPTION` | 提供了不支持的旗帜 |
| `INVALID_OPTION` | 标记缺少一个值或有无效值 |
| `INVALID_ARGUMENT` | 位置参数缺失或冲突 |
| `CONNECTION_STORE_ERROR` | DBX 连接存储已存在但无法读取 |
| `CONNECTION_NOT_FOUND` | 没有匹配请求名称的 DBX 连接 |
| `SQL_BLOCKED` | SQL 安全规则阻碍执行 |
| `DBX_NOT_RUNNING` | DBX 桌面桥没有可用 |
| `HOME_NOT_FOUND` | 默认用户技能目录无法解决 |
| `SKILL_MODIFIED` | 发现未管理或本地编辑的 DBX Skill |
| `SKILL_PATH_UNSAFE` | 管理中的技能路径是一个符号链接 |
| `SKILL_READ_FAILED` | 无法读取已安装的 Skill 文件 |
| `SKILL_WRITE_FAILED` | 捆绑的技能无法安装 |
| `ERROR` | 意外运行时间失败 |

## 代码

Codex可以从 shell 工具直接调用 CLI :

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

## 常见问题

### @dbx-app/cli 是什么？

DBX 数据库连接、 计划和安全查询的命令行接口

### 如何安装 @dbx-app/cli？

在项目目录运行 npm install @dbx-app/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 dbx，可以用 npx dbx 直接运行。

### @dbx-app/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dbx-app\_\_cli 是否存在。

### @dbx-app/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dbx-app/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.18\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dbx-app/cli 可以商用吗？

@dbx-app/cli 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @dbx-app/cli 的下载量有多少？

根据 npm 官方下载统计，@dbx-app/cli 在 2026/10/12 – 2026/11/10 这 30 天内被下载 5,192 次，日均约 173 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dbx-app/cli 还在维护吗？

最新版本 0\.4\.142 发布于 2026/11/11（今天）；至今共发布 134 个版本，其中过去 12 个月发布了 134 个；首次发布于 2026/05/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。