doudian-open-cli 手册

英文主文档：README.md。

抖店开放平台对外 CLI。可执行文件名是 doudian-open-cli。用 init 完成本机授权或写入凭据，再用 api 按路径调用开放接口。不为每个接口单独提供子命令。接口 path 与字段以 开放平台接口文档中心 为准。

本文覆盖安装、登录、命令参数、退出码、输出格式和升级，可作为 CLI 接入手册。参数以各命令 --help 为准。

环境

需要 Node.js 18+，无需 Go。安装后启动器按本机选出包内二进制。

| 平台 | 架构 | |---|---| | Linux | AMD64、ARM64 | | macOS | Intel（x64）、Apple Silicon（ARM64） | | Windows | AMD64 |

其余组合会明确失败。

安装

npm install --global @bytedance/doudian-open-cli@latest
doudian-open-cli --version
doudian-open-cli --help

安装检查：doudian-open-cli --version 在 stdout 打印一行版本号。

可执行文件名是 doudian-open-cli。若再安装另一个同样提供此命令的 npm 包，后装的会覆盖前者。

升级

命令成功时，若缓存里有新版本，stderr 可能多一行非 JSON 提示，不进入 stdout 信封。安装：

doudian-open-cli update
doudian-open-cli --version

--check 只检查。DOUDIAN_OPEN_CLI_NO_UPDATE_NOTIFIER 关闭提示。也可以继续 npm install --global @bytedance/doudian-open-cli@latest。

命令

默认 --output json（也可显式 -o json）。成功数据在 stdout，过程提示和错误在 stderr。人眼扫一眼可加 -o text。skills 除外，见下文。

| 命令 | 作用 | |---|---| | --help、-h | 查看该命令的用法和参数。根命令以及 init、auth、api、skills、update 均支持 | | version / --version | 打印版本号 | | skills | 列出内嵌 Skill：open 在前，随后是业务 Skill；每行 名称<TAB>description | | skills <name> | 打印指定 Skill 的 SKILL.md 原文。不写入本机 Agent 目录，不受 --output json 影响 | | init --kind authorized | 商家授权型登录：打开浏览器并阻塞轮询直到结束 | | init --kind authorized --no-wait | 只发起授权并立刻返回 verification_url，不打开浏览器。有效会话内重复执行会复用，不重新发码 | | init --kind authorized --complete | 用本机待完成会话兑票，阻塞到成功或超时 | | init --kind generic --app-key --app-secret --access-token | 通用型：把开发者自己的 ak/sk/token 写入本地凭据 | | auth status | 只读本地开放凭据（类型、app_key、过期、店铺），不打远端，不打印 token / secret | | auth logout | 删除本地开放凭据。换应用或换类型前先执行 | | api [GET\|POST] --path <path> --data <json> | 按当前凭据调用开放网关。--path 必填，省略 METHOD 时为 POST，只支持 GET / POST。两种身份都带 HMAC sign / sign_method；调用方不附加 sign | | api … --dry-run | 只预览方法、URL、query 键和 body，不发 HTTP，不展示 token / secret / CLI 审计头 | | update | 按当前安装的 npm 包升级。--check 只检查。提示只在 stderr，不进入 JSON |

下文命令均需加上 doudian-open-cli 前缀。

登录

调用接口前必须完成本地初始化。凭据保存在本机，kind 为 authorized（商家浏览器授权）或 generic（开发者填入 app_key / app_secret / access_token）。本地已有凭据时再次 init 会失败；换应用或换类型先 auth logout 再 init。

查看与退出

doudian-open-cli auth status --output json
doudian-open-cli auth logout --output json

• 已登录："authenticated":true，并带 identity（kind、app_key、expires_at 等）。退出码 0。
• 未登录："authenticated":false。退出码仍为 0。
• auth logout 删除本地凭据。成功时 "authenticated":false。

出现以下任一情况时重新登录：authenticated 为 false，expires_at 已过期，或 api 返回 type 为 auth。通用型未填 --expires-at 时，CLI 不在本地判断过期，等网关返回过期后再 init。

商家授权（阻塞轮询）

一条命令发起授权、打开浏览器并等到结束：

doudian-open-cli init --kind authorized --output json

stderr 会打印 请在浏览器打开: <verification_url>。打不开浏览器时再打印 无法打开浏览器，请访问：<verification_url>，进程继续等待。成功后 auth status 中 kind 为 authorized。

商家授权（两段式）

1. 发起授权，立刻返回链接，不写入凭据、不打开浏览器：

doudian-open-cli init --kind authorized --no-wait --output json

把 stdout 里的 verification_url 原样交给用户（保留 query）。stderr 会再打印同一链接。会话仍有效时重复 --no-wait 会复用，不重新发码。

2. 用户完成授权后兑票（可立刻执行，或等用户确认后再执行）：

doudian-open-cli init --kind authorized --complete --output json

没有待完成会话时会失败，提示先 --no-wait。不要让用户自己跑 --complete。不要把 device_code、token、secret 写入对话。device_code 不会打到终端；本地保存在钥匙串加密文件里，不写明文 login-session.json。auth logout 会删掉这份会话和已保存凭据，不会删系统钥匙串里的主密钥。

开发者凭据

三个参数都必填，只写入本地，不进入对话或日志：

doudian-open-cli init --kind generic --app-key "$APP_KEY" --app-secret "$APP_SECRET" --access-token "$ACCESS_TOKEN" --output json

授权型不含 app_secret。两种身份都由 CLI 填写 sign / sign_method（通用型用 app_secret 算 HMAC）。调用方不附加 sign。

输出格式

根命令 -o / --output 为 json（默认）或 text。不加该参数时，init / auth / api 与显式 --output json 相同。Agent 和脚本按默认 json 解析即可，不必再手写 --output json；需要人读短摘要时再加 -o text。

先看进程退出码，再解析对应流。不要把 stderr 当成功 JSON 解析。

json 成功（默认）

stdout 恰好一个 JSON 对象，以换行结束。ok 为 true。过程提示和授权 URL 走 stderr。

api 成功时 data 只等于网关 body 里的 data（例如 {"task_id":"..."}），不是整份网关 JSON。有网关 log_id 时出现在 meta.log_id。授权 init --no-wait 成功时 meta.log_id 来自 device/start 响应头 x-tt-logid；--complete 或一次性 authorized init 成功时来自最后一次 device/token 的同一响应头。失败且已发出请求时，stderr 的 log_id 同样取该头。

auth status 已登录字段：ok、identity、data.authenticated。--dry-run 时还有 dry_run: true。

identity

仅 json 成功 且本机 已有开放凭据 时出现；空字段省略。PublicIdentity 当前只填下面三列，不会输出 token / app_secret，也 不会输出 shop_id / shop_name（结构体有这两个字段，CLI 未填充）。

| 字段 | 何时出现 | |---|---| | kind | authorized 或 generic | | app_key | 凭据里的应用 key | | expires_at | RFC3339。凭据里有过期时间才出现。授权型来自兑票结果；通用型只有 init 传了 --expires-at 才有 |

会带 identity：init 写入凭据成功（generic，或 authorized 等到结束 / --complete）、已登录的 auth status、api 真实调用成功、api --dry-run。

不带 identity：未登录的 auth status、auth logout、init --no-wait（尚未登录）、失败 stderr、skills、-o text（text 成功只有 ok dry_run=...）。

json 失败（默认）

stdout 为空。stderr 一条 JSON：type、message，可能有 hint、log_id、code。开放网关返回其标准失败 JSON 时另有 body（那份 JSON 原文）。CLI 不会把 HTTP 响应头或对端整页原文打出来。

api 若对端返回的不是该 JSON（任意 HTTP 状态，例如 401 / 403 / 502 的 HTML 或纯文本），stderr 只有状态行，例如：

{"type":"api","message":"网关 HTTP 502 Bad Gateway"}

message 固定为 网关 HTTP 加上 HTTP 状态行，对任意状态码同一模板。授权 init 则为 授权 start 返回 HTTP 502 / 授权 token 返回 HTTP 502（只有数字，没有短语）。

text（需显式 -o text）

成功时 stdout 只有一行 ok dry_run=true|false，不打印 data 和 log_id。失败时 stderr 为 type: message，下一行可能是 hint；网关失败再附 body 原文。不要用 text 解析业务字段。

skills 例外

skills 不受 --output 影响。stdout 永远是纯文本，不是 JSON 信封，失败时 stdout 为空。

token、app_secret、device_code 不会出现在 stdout / stderr。

退出码

| 退出码 | type | 含义 | |---|---|---| | 0 | — | 成功 | | 1 | api | 网关或业务返回失败 | | 2 | validation | 参数不合法 | | 3 | auth | 未登录、凭据过期或授权失败。按 hint 重新 init | | 4 | network | 网络错误 | | 5 | internal | CLI 内部错误 |

auth status 在未登录时仍为退出码 0。

命令与参数

下文均需加上 doudian-open-cli 前缀。

全局

| 参数 | 说明 | |---|---| | -h、--help | 打印帮助并退出。根命令以及 init、auth、api、skills 均支持 | | -o、--output | json（默认）或 text。对 skills 无效 | | -v、--version | 仅根命令。打印版本号 | | version | 子命令。与 --version 相同，stdout 一行版本号 |

skills

给 Agent 阅读内嵌说明，不写入本机目录。

doudian-open-cli skills
doudian-open-cli skills open_cli_skill
doudian-open-cli skills <业务名>

无参数：先列出 open，再列出业务 Skill。每行 名称<TAB>description。未知名称退出码 2。

init

没有位置参数。

| 参数 | 说明 | |---|---| | --kind | authorized 或 generic。单独执行 init 时必填。使用 --no-wait 或 --complete 时可以省略，省略后按 authorized 处理 | | --no-wait | 发起授权并返回 verification_url、user_code、expires_in、interval、hint。不能与 --complete、--device-code 同时使用，也不能用于 generic | | --complete | 查询本机未完成的授权，成功后写入凭据。不能用于 generic | | --device-code | 可选。传入时必须与本机未完成会话一致。一般不必传入 | | --app-key | 通用型必填 | | --app-secret | 通用型必填 | | --access-token | 通用型必填 | | --expires-at | 可选，RFC3339。仅通用型。授权型过期时间来自授权结果 |

auth

auth 单独执行没有动作。status / logout 没有专属参数。

api

doudian-open-cli api [GET|POST] --path <path> --data <json> [--dry-run]

METHOD 可省略，省略时为 POST。--path 必填且不接受 path 位置参数；路径必须以 / 开头，若传入完整 URL，只保留路径。只支持 GET、POST。

| 参数 | 说明 | |---|---| | --path | 必填。开放平台接口路径，或可提取 path 的完整 URL | | --data | JSON 对象。POST 必填；GET 可省略，省略后为 {}。支持原文、@文件路径、@- | | --dry-run | 只预览 http_method、path、网关 method、url、query_keys、body，不访问网关。未登录时同样失败 |

doudian-open-cli api POST --path '/product/detail' --data '{}' --dry-run --output json
doudian-open-cli api --path '/product/detail' --data '{"product_id":"..."}' --output json
doudian-open-cli api GET --path '/product/list' --data '{"page":1}' --output json

会改线上数据时，先 --dry-run 并把关键参数交给用户确认，再去掉 --dry-run 发送同一请求。

Agent 用法

1. doudian-open-cli skills 按 description 判断要读哪一份。
2. doudian-open-cli skills open_cli_skill 或 doudian-open-cli skills <业务名> 打印对应 SKILL.md 原文。
3. doudian-open-cli auth status 确认登录（默认 json）；未登录则走上面的 init。
4. doudian-open-cli api … --dry-run 预览后再发送。

本包不把 Skill 安装到本机 Agent 目录。

限制与网络

• 不支持 + 快捷命令、--appkey、api invoke、auth login
• 远程均为 HTTPS：授权与开放网关 https://openapi-fxg.jinritemai.com；接口文档中心 https://op.jinritemai.com/docs/api-docs

示例

以下命令均省略 --output json（默认就是 json）。需要人读短摘要时再加 -o text。先看退出码：0 只解析 stdout；非 0 时 stdout 为空，解析 stderr。

skills

doudian-open-cli skills
doudian-open-cli skills open_cli_skill
doudian-open-cli skills doudian_aigc
doudian-open-cli skills doudian_aigc --ref create_video

无参数 stdout 为纯文本，每行 名称<TAB>description，不受 --output 影响。

auth status（未登录，退出码 0）

doudian-open-cli auth status

stdout：

{"ok":true,"dry_run":false,"data":{"authenticated":false}}

auth status（已登录，退出码 0）

{
  "ok": true,
  "dry_run": false,
  "identity": {
    "kind": "authorized",
    "app_key": "6845161900440045064",
    "expires_at": "2026-10-01T15:29:00+08:00"
  },
  "data": {"authenticated": true}
}

通用型登录

doudian-open-cli init --kind generic \
  --app-key "$APP_KEY" \
  --app-secret "$APP_SECRET" \
  --access-token "$ACCESS_TOKEN"

stdout 类似：

{
  "ok": true,
  "dry_run": false,
  "identity": {"kind": "generic", "app_key": "6845161900440045064"},
  "data": {"kind": "generic", "authenticated": true}
}

未传 --expires-at 时没有 identity.expires_at。

商家授权（两段式）

doudian-open-cli init --kind authorized --no-wait

stdout 含 verification_url、user_code、expires_in、interval、hint。把 verification_url 原样交给用户。用户完成后：

doudian-open-cli init --kind authorized --complete

阻塞轮询用一条命令等到结束：doudian-open-cli init --kind authorized。

本地已有凭据时再次 init 会失败（退出码 3），先 auth logout。

api 预览（不发 HTTP）

doudian-open-cli api POST --path '/product/detail' --data '{}' --dry-run

stdout 的 data 含将要发出的 http_method、path、网关 method、url、query_keys、body，不含 token / secret。

{
  "ok": true,
  "dry_run": true,
  "identity": {
    "kind": "authorized",
    "app_key": "6845161900440045064",
    "expires_at": "2026-10-01T15:29:00+08:00"
  },
  "data": {
    "http_method": "POST",
    "path": "/product/detail",
    "method": "product.detail",
    "url": "https://openapi-fxg.jinritemai.com/product/detail",
    "query_keys": ["access_token", "app_key", "method", "sign", "sign_method", "timestamp", "v"],
    "body": {}
  }
}

api 成功（退出码 0）

网关 code 为 10000 时，CLI 把网关 data 放进信封的 data，log_id 放进 meta.log_id。

doudian-open-cli api POST --path '/contentAigc/createAIVideoTaskOpen' --data '{"...":"..."}'

stdout：

{
  "ok": true,
  "dry_run": false,
  "identity": {
    "kind": "generic",
    "app_key": "7687517554562303517"
  },
  "data": {"task_id": "584875801346"},
  "meta": {"log_id": "20261010113423729861E2FDCC5D1FB32F"}
}

查询、列表同样从 data 读业务字段，例如：

doudian-open-cli api --path '/product/detail' --data '{"product_id":"..."}'
doudian-open-cli api GET --path '/product/list' --data '{"page":1}'

--data 也支持 @文件路径 或 @-（stdin）。

api 网关业务失败（退出码 1）

stdout 为空。stderr：

{
  "type": "api",
  "code": "dop.service-timeout-error",
  "message": "服务内部访问超时，请重试",
  "log_id": "2026092416541870A80A208A3767DE168F",
  "body": {
    "code": 20001,
    "msg": "内部服务超时",
    "sub_code": "dop.service-timeout-error",
    "sub_msg": "服务内部访问超时，请重试",
    "data": null,
    "log_id": "2026092416541870A80A208A3767DE168F"
  }
}

token 失效（退出码 3）

stderr 含 type 为 auth 和 hint，按 hint 重新 init：

{
  "type": "auth",
  "code": "isv.access-token-no-existed",
  "message": "access_token不存在，请使用最新的access_token访问",
  "hint": "先运行 doudian-open-cli init",
  "log_id": "20260924163802231CAD329A205AFAF287",
  "body": {
    "code": 40003,
    "msg": "access_token不存在，请使用最新的access_token访问",
    "sub_code": "isv.access-token-no-existed",
    "sub_msg": "access_token不存在，请使用最新的access_token访问",
    "data": null,
    "log_id": "20260924163802231CAD329A205AFAF287"
  }
}

参数错误（退出码 2）

例如缺少 --data。stderr：{"type":"validation","message":"--data 不能为空"}

非开放平台 JSON 的 HTTP 失败（退出码 1）

对端回了任意非成功 HTTP 状态、且 body 不是开放平台那套 JSON 时，见上文「json 失败」。不要从 stderr 里找响应头或对端原文。

网络超时（退出码 4）

连不上或整次请求超过默认 30s 时走这里，不是「对端回了某个 HTTP 状态码」。超时 stderr 类似：

{"type":"network","message":"Post \"https://openapi-fxg.jinritemai.com/auth/cli/device/start\": context deadline exceeded (Client.Timeout exceeded while awaiting headers)"}

显式 text

doudian-open-cli -o text api --path '/product/detail' --data '{"product_id":"..."}'

成功时 stdout 只有 ok dry_run=false，没有 task_id / log_id。Agent 不要用这种模式。