豆包命令行工具
全部命令、选项与边界条件
doubao CLI 把豆包的能力放到终端里:既可以开一个交互式界面聊天干活,也可以一条命令跑完一个任务就退出,还能把结果按 JSON 吐给脚本。它独立运行,不需要启动桌面端。
三种用法,选一个就够
打开 TUI 界面,多轮对话、看文件、改代码。输入 /help 查交互命令。
跑完一个任务直接退出,适合脚本和定时任务。
把标准输入当上下文喂进去,日志、文档、报错都行。
$ npm install -g '@bytedance/doubao-cli' --registry=https://registry.npmjs.org/ $ doubao --version doubao 2.37.2
安装、升级与平台支持
npm 分发装的是 npm 包,实际运行的是安装脚本下载下来的原生程序。所以 npm 那一步成功不代表能跑,装完必须执行 doubao --version 和 doubao --help,两条都正常才算装上。
| 环节 | 命令 | 说明 |
|---|---|---|
| 安装 / 重装 | npm install -g '@bytedance/doubao-cli' | 默认装 latest;需允许执行 npm 安装脚本,否则原生程序不会落地。 |
| 升级 | doubao update | 先退掉所有 CLI 实例。版本相同会提示已是最新,本机较新时不降级。 |
| 版本 | doubao --version / -v | 免登录,不触发更新检查。 |
| 帮助 | doubao --help / -h | 免登录。注意 -p "--help" 里的 --help 是提示词,不会出帮助。 |
平台只有三个组合:Windows x64、macOS ARM64、Linux x64。Apple Silicon 机器若 node -p "process.arch" 输出 x64,说明用错了 Node,需要先切到 ARM64 版本再装。
装在哪:npm prefix -g 指向的目录下的 bin。要直接敲 doubao,这个 bin 得在 PATH 里;换终端环境(比如另一套 Node)后发现命令找不到,重装一次即可。
账号与登录
4 条命令| 命令 | 登录 | 行为 |
|---|---|---|
doubao login [--qr=small|full|png] | 免 | 未登录时生成二维码;已登录时保留当前会话,不重复扫码。要换账号必须先 logout。 |
doubao logout | 免 | 退出登录,同时停掉当前账号下所有正在运行的任务,并清理共享服务保存的凭证。 |
doubao auth status [--verify] | 免 | 查登录状态。加 --verify 会连共享服务做一次在线验证,必要时尝试恢复本地保存的会话。 |
doubao auth login|logout | 免 | 与 login / logout 等价,另一套写法。 |
二维码的三种形态
--qr=small:终端里的小尺寸字符画,适合窄窗口。--qr=full:终端里的完整字符画,可扫描尺寸更稳。--qr=png:输出QR_IMAGE=<路径>,得到一张临时 PNG。登录流程结束后该图片会被清理,要留档得当场复制走。
$ doubao auth status --verify 登录成功,账号已通过验证 用户 ID:2156619074647994 设备 ID:2979057973864699
未登录时状态命令返回 login_required 并以退出码 4 结束。脚本里可以直接判 $? -eq 4 来区分"没登录"和"登录了但请求失败"。
单次任务 -p
跑完即退-p 后面紧跟提示词,输出结果后进程退出,不留在会话里。这是自动化和脚本调用的主路径。
# 1. 直接给提示词(含空格要整体加引号) $ doubao -p "解释这段代码" # 2. 提示词 + 管道上下文(管道内容追加为上下文) $ cat notes.txt | doubao -p "总结以下内容" # 3. 整段提示词来自管道(要求非空) $ cat prompt.txt | doubao -p - # 4. 指定工作目录 + 指定模型 + JSON 输出 $ doubao -C /path/to/project -p "列出目录结构" --model 5 --output-format json
-C 的位置很关键
-C <目录> 决定工作区和任务运行目录,目录必须存在。它属于 Native 选项,必须放在 -p、--list、model 等业务参数之前,否则会被当成业务参数的一部分。相对路径按启动命令时的当前目录解析。
会话:列表、恢复、导出
跨目录跨设备| 命令 | 作用 |
|---|---|
--list | 列出未归档会话,跨目录、跨设备,默认最多 50 条,输出后退出。 |
--limit <数量> | 限制总条数,仅用于 --list。 |
--all | 读取全部(翻完所有页),仅用于 --list,不能与 --limit 同用。 |
--cursor <游标> | 从上次返回的游标续页。 |
--resume [会话ID] | 恢复指定会话;省略 ID 时打开交互式选择器。 |
--export <会话ID> | 只读导出主会话历史,固定输出 [{query,response}] JSON 数组。 |
限量查询会回传游标
用 --limit 时,文本输出会提示实际条数和续页游标;JSON 对应 result.count 与 result.next_cursor。真实返回长这样:
{
"type": "result", "subtype": "success", "is_error": false,
"result": {
"type": "session_list", "count": 3,
"sessions": [
{ "session_id": "38453543615304962", "title": "团队ATS仪表盘私域站点", "updated_at": "2026-11-20T11:07:46+08:00" }
],
"next_cursor": "eyJzY29wZSI6ImFsbCIs...", "has_more": true
}
}
恢复会话的两个前提
- 裸
--resume(不带 ID)需要标准输入和标准输出都连接终端,在管道或 CI 里会失败,脚本里要带会话 ID。 - 恢复后使用本次调用的目录,不会切回历史目录;需要指定目录就前置
-C。--resume不能与--list同用。
$ doubao -C /path/to/project --resume <会话ID> $ doubao --resume <会话ID> -p "继续分析" --output-format json $ doubao --export <会话ID> > history.json
模型与推理强度
17 个可选doubao model list 列出当前账号可用的模型 ID 和它支持的推理强度。--model 接受 ID 或名称,用名称时必须能唯一匹配;--effort 只能填该模型支持的档位,超范围的档位会被拒。
$ doubao model list # 文本表格 $ doubao model list --json # 机器可读 $ doubao -p "..." --model 5104 --effort max
推理强度共 7 档
none · minimal · low · medium · high · xhigh · max。没有统一的默认值,每个模型自带一个 default,下表右列即为实测返回。
| 模型 | ID | 支持的强度 | 默认 |
|---|---|---|---|
| Auto | 9 | low, medium, high | high |
| 豆包 2.1 Lite | seed-lite-7b | low, medium, high | medium |
| Doubao 2.1 Pro | 5 | low, medium, high | high |
| Doubao 2.1 Turbo | 4 | low, medium, high | high |
| DeepSeek V4.1 Flash | 5101 | low, high, max | high |
| DeepSeek V4 Pro | 5577991426 | none, low, high, max | high |
| deepseek-v4.1-flash-1017 | 9697536258 | 未标注 | — 默认模型 |
| Qwen 4 Max | 12259585282 | low, high, xhigh | high |
| Qwen 3.8 Max | 12259589122 | low, medium, xhigh | xhigh |
| Qwen 3.8 Flash | 6038793474 | low, medium, xhigh | xhigh |
| Kimi K3.1 Pro | 5102 | low, high, max | high |
| Kimi K3.1 Pro 高速 | 9878038274 | low, high, max | high |
| Kimi K3 | 9881096450 | low, high, max | high |
| GLM 5.3 | 5104 | low, high, max | max |
| GLM 5.3 Flash | 10598414850 | minimal ~ max(全 6 档) | max |
| glm-5.3-flash | 1698817026 | low, high, max | max |
| MiniMax-M3.1-Flash | 6743040258 | 未标注 | — |
模型清单随账号权限变化,以上为本机账号在 2.37.2 下的实际返回;换账号后以 doubao model list 为准。
输出格式
仅 -p / --list / model list三种格式:text(默认,给人看)、json(一次性给完整 JSON)、stream-json(逐行 JSON,适合边跑边解析)。--json 等价于 --output-format json,两个同时写会报错。--export 固定输出 JSON 数组,不接受格式参数。
9 Auto efforts: low, medium, high seed-lite-7b 豆包 2.1 Lite efforts: low, medium, high 5 Doubao 2.1 Pro efforts: low, medium, high 5104 GLM 5.3 efforts: low, high, max ...
{
"type": "result", "subtype": "success", "is_error": false,
"result": {
"type": "model_list",
"models": [
{ "id": "5104", "name": "GLM 5.3", "is_default": false,
"efforts": ["low","high","max"], "default_effort": "max" }
]
}
}// 每行一个独立 JSON,适合边读边处理 {"type":"...", ...} {"type":"...", ...} {"type":"result","subtype":"success","is_error":false, ...}
JSON 结果的统一外壳是 {type, subtype, is_error, result},result.type 区分内容类型(model_list、session_list 等)。判断成败看 is_error,不要只看退出码。
权限与沙箱
3 档 + 1 个开关--permission-mode 决定执行过程中哪些动作需要你点确认,决定了自动化能不能无人值守跑完。
每个动作都确认。适合第一次在陌生项目里跑,或涉及生产数据。
只有风险操作才确认。日常改代码、读文件这个档位够用。
允许所有操作,不再询问。脚本、CI 里常用,前提是你信任任务本身。
--dangerously-bypass-approvals-and-sandbox 请求不受限的网络和文件访问,绕过审批与沙箱。它和 --permission-mode 互斥,不能同时写。这个开关只在确实需要访问沙箱外资源时用,别当默认选项。
后台服务任务
常驻进程| 命令 | 登录 | 行为 |
|---|---|---|
--service-start | 需 | 在后台跑服务任务。不能重复启动,已在运行时要先停。 |
--service-stop | 需 | 停止服务任务。 |
--service-status | 免 | 查状态、进程号和运行时长。未开启时明确提示"没有通过 --service-start 启动的服务任务"。 |
它和 -p、--list、model list、--export 都不能同时使用。另外,即使没开服务任务,交互界面仍可能使用共享后台和 dispatch,这是正常现象。
$ doubao --service-status 服务任务状态:未开启 没有通过 --service-start 启动的服务任务。 交互界面仍可能使用共享后台及 dispatch。
输入、管道与长度上限
两个硬上限| 约束 | 取值 |
|---|---|
| 管道输入编码 | 必须 UTF-8 |
| 管道输入体积 | ≤ 1 MiB |
| 最终提示词长度 | ≤ 262,144 个 Unicode 码点(含管道追加的部分) |
| 提示词传参方式 | 必须紧跟 -p,并作为一个完整参数传入;含空格用引号包住 |
| 哪些命令读管道 | 只有 -p;指定了提示词时管道内容追加为上下文,-p - 要求管道非空 |
超长时不要靠截断硬塞。-p - 是把整段管道当提示词,1 MiB 的文件直接进去多半超过 262,144 码点上限;先本地分段,或改用 -C 让 CLI 自己读文件。
互斥与约束矩阵
排错先看这里这套 CLI 的参数解析分两段:前面的 Native 选项由启动器解析,从第一个业务参数起交给前端。所以顺序和组合都有硬规则,写错就是 invalid_arguments。
| 规则 | 具体含义 |
|---|---|
| Native 选项必须前置 | -C、-h、-v 这类要放在业务参数之前。 |
| 五个命令互斥 | -p、--list、model list、--export、--service-start 不能同时使用。 |
--resume + -p | 可以同用,但此时必须指定会话 ID。 |
--resume + --list | 不能同用。 |
裸 --resume | 标准输入和标准输出都必须连接终端,否则失败。 |
model list 的限制 | 不接受 --resume、--model、--effort、权限选项。 |
--export 的限制 | 同上,且固定输出 JSON 数组,不接受输出格式参数。 |
--json 与 --output-format | 不能同时使用。 |
--all 与 --limit | 不能同时使用;--all 只用于 --list。 |
| 权限选项冲突 | --permission-mode 与 --dangerously-bypass-approvals-and-sandbox 互斥。 |
| 输出选项范围 | 只对 -p、--list、model list 生效。 |
报错与退出码
实测几种| 返回 | 退出码 | 处理方式 |
|---|---|---|
login_required | 4 | 没登录。跑 doubao login;脚本里按退出码 4 单独分支。 |
invalid_arguments | — | 参数写错或组合冲突。核对第 11 节,以及子命令是否支持 --help(model list 就不支持)。 |
service_unavailable | — | 连接共享服务超时。等一会儿重试,通常是网络或上游抖动,不是参数问题。 |
几个容易踩的点
doubao命令找不到:全局bin不在 PATH,刷新终端或重装。doubao update提示还有实例在跑:先退出所有 CLI 实例再重试,它不会替你杀进程。- 交互启动时问
Update now? [Y/N]:输 N 继续当前命令;输 Y 会更新并退出,需重新执行。 - 二维码打不开或已过期:换
--qr=png拿到图片路径再看,失效就重新login。
命令速查表
贴到便签上三个最常用的组合
# 进项目里问一次,中间有风险操作会停下来问你 $ doubao -C /path/to/project -p "先看目录结构,再看 README,给我一份上手说明" \ --permission-mode ask_risky
# 日志多了先截尾,避免撞上提示词上限 $ tail -n 200 app.log | doubao -p "找出报错原因,给出修复建议" --model 5 --effort high
# 无人值守 + JSON,方便后续解析 $ for f in docs/*.md; do doubao -C . -p "给 $f 写三行摘要" \ --permission-mode always_allow --output-format json done