# @bytedance/doudian-open-cli 中文文档

规范地址：https://npmcn.com/package/%40bytedance/doudian-open-cli/

版本：1\.0\.2
npm 元数据更新时间：2026-10-22T08:35:48.174Z
中文译文更新时间：2026-11-08T21:50:30.175Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40bytedance/doudian-open-cli
原文对照：https://npmcn.com/package/%40bytedance/doudian-open-cli/?lang=original

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

- 包体积（解压后）：69.1 MB，21 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-10-15T12:21:58.803Z
- 最新版本发布：2026-10-22T08:35:48.001Z
- 近 30 天下载量：96401（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

抖店开放平台 CLI

## 安装

```sh
npm install @bytedance/doudian-open-cli
```

也可以使用：`pnpm add @bytedance/doudian-open-cli`、`yarn add @bytedance/doudian-open-cli`、`bun add @bytedance/doudian-open-cli`

## README

# doudian-open-cli 手册

英文主文档：[README.md](https://npmcn.com/package/%40bytedance/doudian-open-cli/README.md)。

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

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

## 环境

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

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

其余组合会明确失败。

## 安装

```bash
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 信封。安装：

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

### 查看与退出

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

### 商家授权（阻塞轮询）

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

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

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

### 商家授权（两段式）

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

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

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

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

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

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

### 开发者凭据

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

```bash
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 只有状态行，例如：

```json
{"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 阅读内嵌说明，不写入本机目录。

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

```text
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`，不访问网关。未登录时同样失败 |

```bash
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](https://op.jinritemai.com/docs/api-docs)

## 示例

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

### skills

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

```bash
doudian-open-cli auth status
```

stdout：

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

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

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

### 通用型登录

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

stdout 类似：

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

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

### 商家授权（两段式）

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

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

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

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

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

### api 预览（不发 HTTP）

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

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

```json
{
  "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`。

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

stdout：

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

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

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

```json
{
  "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`：

```json
{
  "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 类似：

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

### 显式 text

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

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

## 常见问题

### @bytedance/doudian-open-cli 是什么？

抖店开放平台 CLI

### 如何安装 @bytedance/doudian-open-cli？

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

### @bytedance/doudian-open-cli 支持 TypeScript 吗？

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

### @bytedance/doudian-open-cli 需要什么版本的 Node\.js？

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

### @bytedance/doudian-open-cli 可以商用吗？

@bytedance/doudian-open-cli 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @bytedance/doudian-open-cli 的下载量有多少？

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

### @bytedance/doudian-open-cli 还在维护吗？

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