Dodo CLI

Dodo CLI 可在终端中管理 Dodo Payments 资源、通过内置 AI 助手回答账户相关问题、创建 checkout sessions 并测试 webhooks。你可以使用交互式 TUI，也可以在脚本中运行直接子命令。

Features

交互式 TUI：不带参数运行 dodo，即可打开交互式界面，其中包含命令面板、历史记录和实时通知。
内置 AI 助手：使用 /ai 以自然语言提问或执行操作。该助手在本地运行 dodopayments-mcp，无需额外设置。
加密凭据：API keys 存储在 ~/.dodopayments/config.json 中，并使用 AES-256-GCM 加密，密钥由你的计算机派生。磁盘上不会存储明文凭据。
自动更新：CLI 启动时会检查新版本，并在 TUI 中通知你。对于 npm 和 Bun 安装，运行 /update 即可原地升级。
Webhook 工具：将测试模式 webhooks 转发到本地服务器，或离线发送模拟 webhook payloads。
脚手架：使用 dodo init 向 Next.js、Express 和 Better Auth 项目添加 billing routes。

Installation

在 macOS 或 Linux 上，使用安装脚本安装最新版本的二进制文件：

curl -fsSL https://dodopayments.com/install.sh | sh

该脚本会根据版本发布的 SHA-256 checksums 验证二进制文件。它会将 dodo 安装到 /usr/local/bin、~/.local/bin 和 ~/bin 中第一个可写的目录；如果这些目录都不可写，则安装到 ~/.local/bin。若要安装特定版本，请将 DODO_VERSION environment variable 设置为对应的 tag。若要选择目录，请设置 DODO_INSTALL_DIR。

使用 NPM 或 Bun 安装

如果你已安装 Node.js 或 Bun，可以全局安装 dodopayments-cli package。通过 package manager 安装时，会获取最新发布的版本：

npm install -g dodopayments-cli

bun install -g dodopayments-cli

诸如 dodo login 这样的直接子命令可在 Node.js 18 或更高版本上运行。通过 package manager 安装时，交互式 TUI 还需要 Bun。版本发布的二进制文件不需要任何 runtime。

手动安装（无需 Node / Bun）

如果不想运行远程脚本，可以自行下载二进制文件进行安装。

Download the Binary

从最新的 GitHub Release 中下载适用于你平台的二进制文件。

平台	二进制文件
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`

Rename the Binary to dodo

mv ./dodo-cli-* ./dodo && chmod +x ./dodo

ren .\dodo-cli-windows-x64.exe .\dodo.exe

Move It to a Directory on Your PATH

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

sudo mv ./dodo /usr/local/bin/

move .\dodo.exe C:\Windows\System32\dodo.exe

(Optional) Verify the Download

每个版本都会发布一个 SHA256SUMS.txt 文件。将其下载到二进制文件旁边，然后验证二进制文件：

shasum -a 256 -c SHA256SUMS.txt

身份验证

运行读取或修改账户的命令之前，请使用 API key 登录。若要通过直接子命令登录，请传入 key 及其模式 test 或 live：

dodo login "$DODO_PAYMENTS_API_KEY" test

或者，在交互式 TUI 中运行：

/login

TUI 登录流程：

在浏览器中打开 dashboard 的 Developer → API Keys 页面。
提示你粘贴 API key。
要求你选择 Test Mode 或 Live Mode。

两个命令都会通过向 API 发送请求来验证 key，然后将其加密存储在 ~/.dodopayments/config.json 中。

加密密钥由你的计算机派生，因此存储的凭据只能在该计算机上使用。如果你从 v3.0.x 升级（该版本将 keys 存储在 OS keychain 中），请再次运行 dodo login。旧版明文 ~/.dodopayments/api-key 文件中的 keys 会自动迁移，并删除该文件。

切换模式和退出登录

你可以同时登录一个测试模式 key 和一个 live 模式 key。若要在 TUI 中切换当前模式，请运行 /switch。若要移除存储的 keys：

dodo logout all

/logout

在直接模式下，传入 test、live 或 all。在 TUI 中，/logout 会要求你选择 All accounts、Test Mode 或 Live Mode，然后要求你确认。

用法

你可以使用两种模式运行 CLI。

1. 交互式 TUI（推荐）

不带参数运行 dodo，即可打开交互式界面：

dodo

输入 / 可打开命令面板。不以 / 开头的文本会发送给 AI 助手。

命令	描述
`/help`	显示命令参考
`/update`	检查并安装 CLI 更新
`/login`	使用 API key 进行身份验证
`/logout`	退出一个或所有环境的登录状态
`/switch`	在测试模式和 live 模式之间切换
`/clear`	清除 TUI 屏幕
`/exit`	退出 TUI（也可以输入 `exit`，或按两次 `Esc`）

2. 直接子命令

运行命令而不打开 TUI：

dodo <category> <sub-command> [args...]

例如：

dodo payments list 1
dodo customers list 1
dodo wh trigger payment.success http://localhost:3000/webhook

下面的参考表列出了直接模式下的所有命令。在 TUI 中，将 dodo 替换为 /，例如 /payments list 1。标记为 TUI only 的命令是交互式向导。在直接模式下，这些命令会输出提示，要求你打开 TUI。

AI 助手

使用自然语言询问账户相关问题或执行操作。该助手在你的计算机上运行 dodopayments-mcp，因此无需额外设置或 OAuth 流程。它会使用你存储的 key 从你的计算机调用 Dodo Payments API，并将你的 prompts 发送给 language model。

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

在直接模式下，运行 dodo ai，后跟你的问题。TUI 中的示例：

how much revenue did I make this week?
/ai create a new customer named Acme Inc.
/ai find my last failed payment

助手使用你的当前模式（测试模式或 live 模式），并且只能访问该模式的数据。

项目脚手架

dodo init 会向现有项目添加 Dodo Payments billing routes。它会写入 route 文件，安装匹配的 @dodopayments/* adapter package，并将缺失的 DODO_PAYMENTS_* variables 以占位值追加到 .env 文件中。已存在的文件和变量会被跳过，并且该命令无需登录即可运行。

dodo init <framework>

脚手架	描述
`dodo init nextjs`	使用 `@dodopayments/nextjs` 为 Next.js App Router 构建 billing routes 脚手架（checkout、customer portal 和 webhook handlers）
`dodo init express`	使用 `@dodopayments/express` 为 Express server 构建 billing routes 脚手架
`dodo init better-auth`	使用 `@dodopayments/better-auth` 构建 Better-Auth plugin 配置脚手架

对于 Better-Auth 脚手架，你可以传入以逗号分隔的 plugins 列表来生成：checkout、portal、usage 和 webhooks。不传列表时，会生成全部四个。

# Scaffold every Better-Auth plugin (default)
dodo init better-auth

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

如果你的项目包含 src/ 目录，脚手架工具会将文件写入其中。它会根据项目的 lock file（bun、pnpm 或 yarn）选择 install command；如果未找到，则使用 npm。

命令参考

这些命令需要已登录的 API key。List commands 接受可选的页码，默认为 1，每页最多显示 100 个项目。

Products

管理产品目录。

命令	描述
`dodo products list <page>`	列出 products
`dodo products create`	打开 dashboard 以创建 product
`dodo products info <id>`	查看特定 product 的详细信息

Payments

查看 payment transactions。

命令	描述
`dodo payments list <page>`	列出 payments
`dodo payments info <id>`	获取特定 payment 的信息

Customers

管理 customers。

命令	描述
`dodo customers list <page>`	列出 customers
`dodo customers create`	创建新 customer（TUI only）
`dodo customers update <id>`	更新现有 customer（TUI only）
`dodo customers portal <id>`	为 customer 创建临时 Customer Portal session

Discounts

管理 discount codes。

命令	描述
`dodo discounts list <page>`	列出 discounts
`dodo discounts create`	创建新的 percentage-based discount（TUI only）
`dodo discounts delete <id>`	按 ID 移除 discount（TUI only）

Licenses

查看 license keys。该命令的拼写为 licences。

命令	描述
`dodo licences list <page>`	列出 licenses

Addons

管理 product add-ons。

命令	描述
`dodo addons list <page>`	列出 addons
`dodo addons create`	打开 dashboard 以创建 addon
`dodo addons info <id>`	查看特定 addon 的详细信息

Refunds

查看 refund information。

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

Checkout

创建 hosted checkout sessions。

命令	描述
`dodo checkout new`	以交互方式创建 hosted checkout session 并获取 payment link（TUI only）

Webhooks

CLI 提供两个用于开发的 webhook 工具：用于将测试模式 webhooks 转发到本地服务器的 listener，以及向任意 endpoint 发送模拟 webhook payloads 的 trigger。

命令	描述
`dodo wh listen <url>`	实时监听 webhooks，并将其转发到本地开发服务器
`dodo wh trigger <event> <url>`	发送模拟 webhook event，即使未登录也可以使用

在直接模式下，必须提供 arguments。在 TUI 中，不带参数运行 /wh listen 或 /wh trigger，即可打开交互式向导。

监听 Webhooks

将 Dodo Payments 账户中的 webhooks 实时转发到本地开发服务器。

dodo wh listen 需要 Test Mode API key。listen flow 不支持 Live Mode keys。

dodo wh listen http://localhost:3000/webhook

Enter Your Local Endpoint URL

传入用于接收 webhooks 的本地 URL，例如 http://localhost:3000/webhook。在 TUI wizard 中，CLI 会提示你输入该 URL。

Automatic Setup

如果你的账户没有用于 CLI relay server 的 webhook endpoint，CLI 会创建一个。该 endpoint 会显示在 Developer → Webhooks 中。随后，CLI 会与 relay 建立 WebSocket connection，以实时接收 events。

Receive and Forward

webhook event 触发时（例如测试 payment 或 subscription change），CLI 会将 payload 和 headers 作为 POST request 转发到本地 endpoint。它会记录 event type 和 endpoint 的 response，并将 response 发送回 relay。

listener 转发到本地 endpoint 时会保留原始 webhook headers（webhook-id、webhook-signature、webhook-timestamp），因此你可以测试 signature verification logic。

中继和 CLI 会解析 JSON body，并在转发之前再次将其序列化。如果转发的 body 与原始内容逐字节不同（例如数字格式不同），即使 headers 完好无损，签名验证也会失败。

触发测试 Webhooks

向任意 endpoint 发送模拟 webhook payload，而不会创建真实 transactions。

触发的 events 不会签名：request 不包含 webhook-id、webhook-signature 或 webhook-timestamp header。测试时，请使用未经验证的方法解析它们（TypeScript 中使用 unsafeUnwrap，Python 中使用 unsafe_unwrap，Go 中使用 UnsafeUnwrap），而不是使用 unwrap；上线前请切换回 unwrap。

dodo wh trigger payment.success http://localhost:3000/webhook

在直接模式下，payload 使用占位 IDs 和 customer details。TUI 中的 /wh trigger wizard 会引导你完成以下操作：

设置目标 endpoint URL。
可选地为 payload 输入 Business ID、Product ID、Metadata（JSON object）、Customer email 和 Customer ID。空白字段会使用占位值。
从交互式菜单中选择要发送的 event。你可以连续发送多个 events。选择 exit 完成操作。

dodo wh trigger 无需登录。它是一个本地离线 webhook payload generator。

支持的 Webhook Events

dodo wh trigger 可以为 Dodo Payments 交付的 48 种 event types 中的 46 种发送模拟 payload。它不支持 subscription.past_due 或 subscription.unpaused。请完全按照以下列表传入 event name：

类别	Events
Subscription	`subscription.active`, `subscription.updated`, `subscription.on_hold`, `subscription.renewed`, `subscription.plan_changed`, `subscription.cancelled`, `subscription.failed`, `subscription.expired`, `subscription.paused`, `subscription.update_payment_method`
Payment	`payment.success`, `payment.failed`, `payment.processing`, `payment.cancelled`
Refund	`refund.success`, `refund.failed`
Dispute	`dispute.opened`, `dispute.expired`, `dispute.accepted`, `dispute.cancelled`, `dispute.challenged`, `dispute.won`, `dispute.lost`
License Key	`licence.created`
Payout	`payout.created`, `payout.in_progress`, `payout.on_hold`, `payout.failed`, `payout.success`
Credit	`credit.added`, `credit.deducted`, `credit.expired`, `credit.rolled_over`, `credit.rollover_forfeited`, `credit.overage_charged`, `credit.overage_reset`, `credit.manual_adjustment`, `credit.balance_low`
Abandoned Checkout	`abandoned_checkout.detected`, `abandoned_checkout.recovered`
Dunning	`dunning.started`, `dunning.recovered`
Entitlement Grant	`entitlement_grant.created`, `entitlement_grant.delivered`, `entitlement_grant.failed`, `entitlement_grant.revoked`

三个 trigger names 与 payload 中发送的 event type 不同：payment.success 发送 payment.succeeded，refund.success 发送 refund.succeeded，而 licence.created 发送 license_key.created。

模拟 payload 的结构遵循 API reference 中对应的 schemas。请参阅 Webhook Events，了解每个 event 的含义，以及 Dodo Payments 在 production 中何时发出该 event。

payout.created 发出时，payout 仍报告 not_initiated status，因此模拟 payload 也会反映这一点。请参阅 Payout Events，了解完整的 payout lifecycle。

Environment Variables

此 variable 会改变 dodo wh listen 的连接方式：

Variable	Description
`DODO_WH_TEST_SERVER_URL`	覆盖 `dodo wh listen` 使用的默认 webhook relay server。设置不带 scheme 的 host name。

更新

CLI 启动时会检查更新版本；如果有可用更新，会在 status bar 中显示通知。若要在 TUI 中升级 npm 或 Bun 安装，请运行：

/update

/update 无法升级 release binary。对于 binary installs（包括通过 install script 安装的版本），它会改为链接到最新的 GitHub release。若要从 shell 升级，请重新运行安装时使用的命令：

curl -fsSL https://dodopayments.com/install.sh | sh

npm install -g dodopayments-cli

bun install -g dodopayments-cli

资源

GitHub Repository

源代码和版本发布信息。

npm Package

npm registry 中的 dodopayments-cli package。

支持

Discord：加入社区服务器。
GitHub：在repository 中提交 issue。
Email：联系 support@dodopayments.com。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Features

Installation

使用 NPM 或 Bun 安装

手动安装（无需 Node / Bun）

身份验证

切换模式和退出登录

用法

1. 交互式 TUI（推荐）

2. 直接子命令

AI 助手

项目脚手架

命令参考

Products

Payments

Customers

Discounts

Licenses

Addons

Refunds

Checkout

Webhooks

监听 Webhooks

触发测试 Webhooks

支持的 Webhook Events

Environment Variables

更新

资源

GitHub Repository

npm Package

支持

​Features

​Installation

​使用 NPM 或 Bun 安装

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

​身份验证

​切换模式和退出登录

​用法

​1. 交互式 TUI（推荐）

​2. 直接子命令

​AI 助手

​项目脚手架

​命令参考

​Products

​Payments

​Customers

​Discounts

​Licenses

​Addons

​Refunds

​Checkout

​Webhooks

​监听 Webhooks

​触发测试 Webhooks

​支持的 Webhook Events

​Environment Variables

​更新

​资源

GitHub Repository

npm Package

​支持

Features

Installation

使用 NPM 或 Bun 安装

手动安装（无需 Node / Bun）

身份验证

切换模式和退出登录

用法

1. 交互式 TUI（推荐）

2. 直接子命令

AI 助手

项目脚手架

命令参考

Products

Payments

Customers

Discounts

Licenses

Addons

Refunds

Checkout

Webhooks

监听 Webhooks

触发测试 Webhooks

支持的 Webhook Events

Environment Variables

更新

资源

支持