$ doubao CLI v2.37.2
命令手册 按 2.37.2 帮助输出与实际运行整理
Command Reference

豆包命令行工具
全部命令、选项与边界条件

doubao CLI 把豆包的能力放到终端里:既可以开一个交互式界面聊天干活,也可以一条命令跑完一个任务就退出,还能把结果按 JSON 吐给脚本。它独立运行,不需要启动桌面端。

包名 @bytedance/doubao-cli Node ≥18 平台 win32-x64 / darwin-arm64 / linux-x64 命令 6 组 模型 17 个

三种用法,选一个就够

交互
doubao

打开 TUI 界面,多轮对话、看文件、改代码。输入 /help 查交互命令。

单次
doubao -p "提示词"

跑完一个任务直接退出,适合脚本和定时任务。

管道
cat x.txt | doubao -p "总结"

把标准输入当上下文喂进去,日志、文档、报错都行。

install
$ npm install -g '@bytedance/doubao-cli' --registry=https://registry.npmjs.org/
$ doubao --version
doubao 2.37.2
02

安装、升级与平台支持

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)后发现命令找不到,重装一次即可。

03

账号与登录

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
i

未登录时状态命令返回 login_required 并以退出码 4 结束。脚本里可以直接判 $? -eq 4 来区分"没登录"和"登录了但请求失败"。

04

单次任务 -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 等业务参数之前,否则会被当成业务参数的一部分。相对路径按启动命令时的当前目录解析。

05

会话:列表、恢复、导出

跨目录跨设备
命令作用
--list列出未归档会话,跨目录、跨设备,默认最多 50 条,输出后退出。
--limit <数量>限制总条数,仅用于 --list。
--all读取全部(翻完所有页),仅用于 --list,不能与 --limit 同用。
--cursor <游标>从上次返回的游标续页。
--resume [会话ID]恢复指定会话;省略 ID 时打开交互式选择器。
--export <会话ID>只读导出主会话历史,固定输出 [{query,response}] JSON 数组。

限量查询会回传游标

用 --limit 时,文本输出会提示实际条数和续页游标;JSON 对应 result.count 与 result.next_cursor。真实返回长这样:

doubao --list --limit 3 --json
{
  "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
06

模型与推理强度

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支持的强度默认
Auto9low, medium, highhigh
豆包 2.1 Liteseed-lite-7blow, medium, highmedium
Doubao 2.1 Pro5low, medium, highhigh
Doubao 2.1 Turbo4low, medium, highhigh
DeepSeek V4.1 Flash5101low, high, maxhigh
DeepSeek V4 Pro5577991426none, low, high, maxhigh
deepseek-v4.1-flash-10179697536258未标注— 默认模型
Qwen 4 Max12259585282low, high, xhighhigh
Qwen 3.8 Max12259589122low, medium, xhighxhigh
Qwen 3.8 Flash6038793474low, medium, xhighxhigh
Kimi K3.1 Pro5102low, high, maxhigh
Kimi K3.1 Pro 高速9878038274low, high, maxhigh
Kimi K39881096450low, high, maxhigh
GLM 5.35104low, high, maxmax
GLM 5.3 Flash10598414850minimal ~ max(全 6 档)max
glm-5.3-flash1698817026low, high, maxmax
MiniMax-M3.1-Flash6743040258未标注—

模型清单随账号权限变化,以上为本机账号在 2.37.2 下的实际返回;换账号后以 doubao model list 为准。

07

输出格式

仅 -p / --list / model list

三种格式:text(默认,给人看)、json(一次性给完整 JSON)、stream-json(逐行 JSON,适合边跑边解析)。--json 等价于 --output-format json,两个同时写会报错。--export 固定输出 JSON 数组,不接受格式参数。

doubao model list
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
...
doubao model list --json
{
  "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" }
    ]
  }
}
--output-format stream-json
// 每行一个独立 JSON,适合边读边处理
{"type":"...", ...}
{"type":"...", ...}
{"type":"result","subtype":"success","is_error":false, ...}
i

JSON 结果的统一外壳是 {type, subtype, is_error, result},result.type 区分内容类型(model_list、session_list 等)。判断成败看 is_error,不要只看退出码。

08

权限与沙箱

3 档 + 1 个开关

--permission-mode 决定执行过程中哪些动作需要你点确认,决定了自动化能不能无人值守跑完。

最保守
ask_always

每个动作都确认。适合第一次在陌生项目里跑,或涉及生产数据。

折中
ask_risky

只有风险操作才确认。日常改代码、读文件这个档位够用。

最放开
always_allow

允许所有操作,不再询问。脚本、CI 里常用,前提是你信任任务本身。

!

--dangerously-bypass-approvals-and-sandbox 请求不受限的网络和文件访问,绕过审批与沙箱。它和 --permission-mode 互斥,不能同时写。这个开关只在确实需要访问沙箱外资源时用,别当默认选项。

09

后台服务任务

常驻进程
命令登录行为
--service-start需在后台跑服务任务。不能重复启动,已在运行时要先停。
--service-stop需停止服务任务。
--service-status免查状态、进程号和运行时长。未开启时明确提示"没有通过 --service-start 启动的服务任务"。

它和 -p、--list、model list、--export 都不能同时使用。另外,即使没开服务任务,交互界面仍可能使用共享后台和 dispatch,这是正常现象。

doubao --service-status
$ doubao --service-status
服务任务状态:未开启
没有通过 --service-start 启动的服务任务。
交互界面仍可能使用共享后台及 dispatch。
10

输入、管道与长度上限

两个硬上限
约束取值
管道输入编码必须 UTF-8
管道输入体积≤ 1 MiB
最终提示词长度≤ 262,144 个 Unicode 码点(含管道追加的部分)
提示词传参方式必须紧跟 -p,并作为一个完整参数传入;含空格用引号包住
哪些命令读管道只有 -p;指定了提示词时管道内容追加为上下文,-p - 要求管道非空
!

超长时不要靠截断硬塞。-p - 是把整段管道当提示词,1 MiB 的文件直接进去多半超过 262,144 码点上限;先本地分段,或改用 -C 让 CLI 自己读文件。

11

互斥与约束矩阵

排错先看这里

这套 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 生效。
12

报错与退出码

实测几种
返回退出码处理方式
login_required4没登录。跑 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。
13

命令速查表

贴到便签上
doubao交互界面
doubao -p "…"单次任务
doubao -p - < prompt.txt整段提示词
doubao -C /path -p "…"指定目录
doubao login --qr=png扫码登录
doubao logout退出并停任务
doubao auth status --verify验证会话
doubao model list可用模型
doubao model list --json模型 JSON
doubao --list最近会话
doubao --list --all全部会话
doubao --list --limit 10 --json限量+JSON
doubao --resume <ID>恢复会话
doubao --resume <ID> -p "…"续跑一次
doubao --export <ID>导出历史
doubao --service-start起后台服务
doubao --service-stop停后台服务
doubao --service-status服务状态
doubao --version版本
doubao update升级

三个最常用的组合

日常
# 进项目里问一次,中间有风险操作会停下来问你
$ 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