> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dodo CLI

> Dodo Payments 的官方命令行界面——从终端管理资源、运行由 AI 驱动的查询、创建结账会话并测试 webhook。

从终端管理您的 Dodo Payments 资源、运行针对您帐户的 AI 驱动查询、创建结账会话并测试 webhook。CLI 附带交互式 TUI、由 MCP 提供支持的内置 AI 助手和离线 webhook 测试。

<iframe className="w-full aspect-video rounded-md" src="https://www.youtube.com/embed/gwtvQsANbW4" title="Dodo CLI | Dodo Payments" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 功能

* **交互式 TUI** — 使用 `dodo` 启动完整的交互界面，包含命令面板、历史记录和实时通知，无需参数。
* **内置 AI 助手** — 使用 `/ai` 用简单的英语提问或执行操作。无需额外设置，本地运行 `dodopayments-mcp`。
* **默认安全** — API 密钥存储在您的操作系统秘密存储中（macOS 钥匙串、Windows 凭证库、Linux libsecret）。磁盘上没有明文配置。
* **自动更新** — CLI 在启动时检查新版本，并在应用内通知您。运行 `/update` 以就地升级。
* **Webhook 工具** — 监听实时 webhooks 或在本地开发时离线触发有效负载。

## 安装

在 macOS 或 Linux 上一行安装 CLI：

```bash theme={null}
curl -fsSL https://dodopayments.com/install.sh | sh
```

### 使用 npm 或 Bun 安装

如果您已经有 Node 或 Bun，包管理器的安装始终拉取最新版本：

```bash npm theme={null}
npm install -g dodopayments-cli
```

```bash Bun theme={null}
bun install -g dodopayments-cli
```

### 手动安装（无需 Node / Bun）

如果您不想将远程脚本传递给 `sh`，请自己下载二进制文件。

从最新的 [GitHub Release](https://github.com/dodopayments/dodopayments-cli/releases) 下载适用于您平台的二进制文件。

| 平台                    | 二进制文件                      |
| --------------------- | -------------------------- |
| macOS (Apple Silicon) | `dodo-cli-darwin-arm64`    |
| macOS (Intel)         | `dodo-cli-darwin-x64`      |
| Linux (x86\_64)       | `dodo-cli-linux-x64`       |
| Linux (arm64)         | `dodo-cli-linux-arm64`     |
| Windows (x86\_64)     | `dodo-cli-windows-x64.exe` |

```bash Linux / macOS theme={null}
mv ./dodo-cli-* ./dodo && chmod +x ./dodo
```

```powershell Windows theme={null}
ren .\dodo-cli-windows-x64.exe .\dodo.exe
```

```bash Linux / macOS theme={null}
sudo mv ./dodo /usr/local/bin/
```

```powershell Windows theme={null}
move .\dodo.exe C:\Windows\System32\dodo.exe
```

在 Windows 上，移动到 `C:\Windows\System32` 需要管理员权限。

每个版本都会发布 `SHA256SUMS.txt`。验证您的下载：

```bash theme={null}
shasum -a 256 -c SHA256SUMS.txt
```

## 认证

在使用认证命令之前，请使用您的 API 密钥登录：

```bash theme={null}
dodo login
```

或者，在交互式 TUI 内：

```text theme={null}
/login
```

登录流程将：

1. 打开您的浏览器访问 Dodo Payments API 密钥页面。
2. 提示您粘贴您的 API 密钥。
3. 要求您选择一个环境——**测试模式** 或 **实时模式**。
4. 将凭据存储在您的操作系统秘密存储中（macOS 上的钥匙串，Windows 上的凭证库，Linux 上的 libsecret）。

由于凭据存储在操作系统的秘密存储中，CLI 首次读取或写入凭据时，可能会提示您输入**设备密码**。如果您从旧版本升级，任何现有的明文 API 密钥将自动**迁移到秘密存储并删除旧文件**。

### 切换模式和注销

您可以同时保持一个**测试模式**和一个**实时模式**密钥进行认证。要清除凭据：

```bash Direct theme={null}
dodo logout
```

```text TUI theme={null}
/logout
```

注销流程允许您独立选择**所有帐户**、**测试模式**或**实时模式**。

## 使用方法

您可以以两种模式使用 CLI。

### 1. 交互式 TUI（推荐）

不带参数运行 `dodo` 启动完整的交互界面：

```bash theme={null}
dodo
```

输入 `/` 打开命令面板，或者直接开始输入——任何不是斜杠命令的内容都会发送给 AI 助手。

| 命令        | 描述                                |
| --------- | --------------------------------- |
| `/help`   | 显示命令参考                            |
| `/update` | 检查并安装 CLI 更新                      |
| `/login`  | 使用 API 密钥进行认证                     |
| `/logout` | 从一个或所有环境中注销                       |
| `/clear`  | 清除 TUI 屏幕                         |
| `/exit`   | 退出 TUI（也可以：输入 `exit`，或者按两次 `Esc`） |

### 2. 直接子命令

不进入 TUI 直接运行命令：

```bash theme={null}
dodo <category> <sub-command> [args...]
```

例如：

```bash theme={null}
dodo payments list 1
dodo customers create
dodo wh trigger
```

下面的参考表显示了每个命令。在 TUI 中，以 `/` 为前缀；在直接模式中，去掉 `/`。

## AI 助手

以自然语言提问或采取行动。助手使用本地运行的 `dodopayments-mcp`——无需额外设置或 OAuth 流程，您的 AI 流量不会离开您的机器，除非与模型提供商通信。

| 命令            | 描述                 |
| ------------- | ------------------ |
| `/ai <query>` | 向 AI 助手提问或给出指令     |
| *(任何非斜杠文本)*   | 在 TUI 中默认发送给 AI 助手 |

示例：

```text theme={null}
how much revenue did I make this week?
/ai create a new customer named Acme Inc.
/ai find my last failed payment
```

助手会尊重您的活动环境（测试/实时），因此它仅对您当前登录的环境的数据进行操作。

## 项目脚手架

`dodo init` 将 Dodo Payments 计费路由直接生成到现有项目中。它生成样板路由文件，安装匹配的 `@dodopayments/*` 适配器包，并安全地将 `DODO_PAYMENTS_*` 环境变量写入您的 `.env`（仅附加未出现的变量）。此命令无需登录即可运行。

```bash theme={null}
dodo init <framework>
```

| 脚手架                     | 描述                                                                           |
| ----------------------- | ---------------------------------------------------------------------------- |
| `dodo init nextjs`      | 使用 `@dodopayments/nextjs` 为 Next.js App Router 生成计费路由（结账、客户门户和 webhook 处理程序） |
| `dodo init express`     | 使用 `@dodopayments/express` 为 Express 服务器生成计费路由                               |
| `dodo init better-auth` | 使用 `@dodopayments/better-auth` 为 Better-Auth 插件配置生成脚手架                       |

对于 Better-Auth 脚手架，您可以传递以逗号分隔的插件列表以生成（默认为所有）：`checkout`，`portal`，`usage`，`webhooks`。

```bash theme={null}
# Scaffold every Better-Auth plugin (default)
dodo init better-auth

# Scaffold only specific plugins
dodo init better-auth checkout,portal
```

脚手架会自动检测 `src/` 目录并相应调整输出路径，并自动检测您的包管理器（`bun`，`pnpm`，`yarn`，或 `npm`）以运行正确的安装命令。

## 命令参考

### 产品

管理您的产品目录。

| 命令                          | 描述          |
| --------------------------- | ----------- |
| `dodo products list <page>` | 列出产品        |
| `dodo products create`      | 打开仪表板创建产品   |
| `dodo products info <id>`   | 查看特定产品的详细信息 |

### 支付

查看支付交易。

| 命令                          | 描述          |
| --------------------------- | ----------- |
| `dodo payments list <page>` | 列出支付        |
| `dodo payments info <id>`   | 获取有关特定支付的信息 |

### 客户

管理您的客户群。

| 命令                           | 描述     |
| ---------------------------- | ------ |
| `dodo customers list <page>` | 列出客户   |
| `dodo customers create`      | 创建新客户  |
| `dodo customers update <id>` | 更新现有客户 |

### 折扣

管理优惠券和折扣。

| 命令                           | 描述         |
| ---------------------------- | ---------- |
| `dodo discounts list <page>` | 列出折扣       |
| `dodo discounts create`      | 创建新的百分比折扣  |
| `dodo discounts delete <id>` | 通过 ID 删除折扣 |

### 许可证

管理软件许可证。

| 命令                          | 描述    |
| --------------------------- | ----- |
| `dodo licences list <page>` | 列出许可证 |

### 附加组件

管理产品附加组件。

| 命令                        | 描述            |
| ------------------------- | ------------- |
| `dodo addons list <page>` | 列出附加组件        |
| `dodo addons create`      | 打开仪表板创建附加组件   |
| `dodo addons info <id>`   | 查看特定附加组件的详细信息 |

### 退款

查看退款信息。

| 命令                         | 描述          |
| -------------------------- | ----------- |
| `dodo refunds list <page>` | 列出退款        |
| `dodo refunds info <id>`   | 查看特定退款的详细信息 |

### 结账

创建托管结账会话。

| 命令                  | 描述                 |
| ------------------- | ------------------ |
| `dodo checkout new` | 交互式创建托管结账会话并获取支付链接 |

## Webhooks

CLI 包含两个用于开发期间测试 webhook 的强大工具：一个**监听器**，将实时测试 webhooks 转发到您的本地服务器，以及一个**触发器**，将模拟 webhook 有效负载发送到任何端点。

| 命令                | 描述                            |
| ----------------- | ----------------------------- |
| `dodo wh listen`  | 实时监听 webhooks 并将其转发到您的本地开发服务器 |
| `dodo wh trigger` | 交互式触发测试 webhook 事件——即使您未登录    |

### 监听 webhooks

将来自 Dodo Payments 的 webhooks 实时转发到您的本地开发服务器。

```bash theme={null}
dodo wh listen
```

提供您希望接收 webhooks 的本地 URL（例如，`http://localhost:3000/webhook`）。

CLI 会自动在您的 Dodo Payments 帐户上创建一个 webhook 端点（如果还不存在），然后打开一个 WebSocket 连接以实时接收事件。

当有 webhook 事件触发（来自测试支付、订阅更改等）时，CLI 会接收并记录活动类型，并将完整请求与头和主体一同转发到您的本地端点。您的端点的响应将被记录并发送回去。

`dodo wh listen` 需要一个**测试模式** API 密钥。监听流程不支持实时模式密钥。

监听器在转发到您的本地端点时保留了原始 webhook 标头（`webhook-id`、`webhook-signature`、`webhook-timestamp`），以便您测试签名验证逻辑。

### 触发测试 webhooks

将模拟的 webhook 有效负载发送到任何端点进行快速测试，无需创建真实交易。

```bash theme={null}
dodo wh trigger
```

`/wh trigger` 流程将引导您完成：

1. 设置目标**端点 URL**
2. 从交互式菜单中选择一个特定的**事件**以触发

`dodo wh trigger` 不需要登录。它可以作为本地/离线 webhook 有效负载生成器。

触发的事件**没有签名**。在测试时，请禁用端点上的 webhook 签名验证——例如，在测试期间，使用 `unsafe_unwrap()` 而不是 `unwrap()` 编写 webhook 处理程序。

### 支持的 webhook 事件

| 类别               | 事件                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------- |
| **Subscription** | `active`, `updated`, `on_hold`, `renewed`, `plan_changed`, `cancelled`, `failed`, `expired` |
| **Payment**      | `succeeded`, `failed`, `processing`, `cancelled`                                            |
| **Refund**       | `succeeded`, `failed`                                                                       |
| **Dispute**      | `opened`, `expired`, `accepted`, `cancelled`, `challenged`, `won`, `lost`                   |
| **License**      | `created`                                                                                   |

### 环境变量

| 变量                        | 描述                                          |
| ------------------------- | ------------------------------------------- |
| `DODO_WH_TEST_SERVER_URL` | 覆盖 `dodo wh listen` 使用的默认 webhook 中继服务器 URL |

## 更新

CLI 在启动时检查是否存在新版本，并在状态栏中提供通知。当一个可用版本出现时，您会收到通知。要升级：

```text theme={null}
/update
```

或者，重新运行安装程序以就地升级：

```bash install.sh theme={null}
curl -fsSL https://dodopayments.com/install.sh | sh
```

```bash npm theme={null}
npm install -g dodopayments-cli
```

```bash Bun theme={null}
bun install -g dodopayments-cli
```

## 资源

查看源代码和发布

查看 npm 注册表

## 支持

* **Discord**: 加入我们的[社区服务器](https://discord.gg/bYqAp4ayYh)
* **GitHub**: 在[仓库](https://github.com/dodopayments/dodopayments-cli/issues)上打开一个问题
* **Email**: 发邮件至 [support@dodopayments.com](mailto:support@dodopayments.com)