Dodo CLI

Dodo CLI quản lý tài nguyên Dodo Payments, trả lời các câu hỏi về tài khoản bằng trợ lý AI tích hợp, tạo phiên checkout và kiểm thử webhook, tất cả ngay từ terminal. Sử dụng TUI tương tác hoặc chạy các subcommand trực tiếp từ script.

Tính năng

TUI tương tác: Chạy dodo không kèm tham số để mở giao diện tương tác với bảng lệnh, lịch sử và thông báo theo thời gian thực.
Trợ lý AI tích hợp: Đặt câu hỏi hoặc thực hiện tác vụ bằng tiếng Anh thông thường với /ai. Trợ lý chạy dodopayments-mcp cục bộ và không cần thiết lập thêm.
Thông tin xác thực được mã hóa: API key được lưu trong ~/.dodopayments/config.json, mã hóa bằng AES-256-GCM với khóa được tạo từ máy của bạn. Không có thông tin xác thực dạng plaintext nào được lưu trên ổ đĩa.
Tự động cập nhật: CLI kiểm tra phiên bản mới khi khởi động và thông báo cho bạn trong TUI. Với các bản cài đặt npm và Bun, chạy /update để nâng cấp trực tiếp.
Công cụ webhook: Chuyển tiếp webhook ở test mode đến server cục bộ hoặc gửi payload webhook giả lập khi offline.
Tạo cấu trúc ban đầu: Thêm các billing route vào dự án Next.js, Express và Better Auth bằng dodo init.

Cài đặt

Trên macOS hoặc Linux, cài binary của bản phát hành mới nhất bằng install script:

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

Script xác minh binary bằng các checksum SHA-256 của bản phát hành. Script cài dodo vào thư mục có quyền ghi đầu tiên trong số /usr/local/bin, ~/.local/bin và ~/bin, hoặc vào ~/.local/bin nếu không thư mục nào có quyền ghi. Để cài một bản phát hành cụ thể, đặt biến môi trường DODO_VERSION thành tag của bản đó. Để chọn thư mục, đặt DODO_INSTALL_DIR.

Cài đặt bằng NPM hoặc Bun

Nếu có Node.js hoặc Bun, hãy cài package dodopayments-cli trên toàn cục. Việc cài đặt bằng package manager sẽ lấy phiên bản mới nhất được phát hành:

npm install -g dodopayments-cli

bun install -g dodopayments-cli

Các subcommand trực tiếp như dodo login chạy trên Node.js 18 trở lên. Khi cài đặt thông qua package manager, TUI tương tác cũng cần Bun. Binary của bản phát hành không cần runtime nào.

Cài đặt thủ công (Không cần Node / Bun)

Để cài đặt mà không chạy script từ xa, hãy tự tải binary xuống.

Download the Binary

Tải binary dành cho nền tảng của bạn từ GitHub Release mới nhất.

Nền tảng	Binary
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

Trên Windows, việc di chuyển file đến C:\Windows\System32 yêu cầu quyền quản trị viên.

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

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

(Optional) Verify the Download

Mỗi bản phát hành cung cấp một file SHA256SUMS.txt. Hãy tải file này xuống cùng thư mục với binary, sau đó xác minh binary:

shasum -a 256 -c SHA256SUMS.txt

Xác thực

Đăng nhập bằng API key trước khi chạy các lệnh đọc hoặc thay đổi tài khoản. Để đăng nhập bằng subcommand trực tiếp, truyền key và mode của key, test hoặc live:

dodo login "$DODO_PAYMENTS_API_KEY" test

Hoặc từ bên trong TUI tương tác:

/login

Quy trình đăng nhập TUI:

Mở trang Developer → API Keys của dashboard trong trình duyệt.
Yêu cầu bạn dán API key.
Yêu cầu bạn chọn Test Mode hoặc Live Mode.

Cả hai lệnh đều xác minh key bằng một request đến API, sau đó lưu key ở dạng mã hóa trong ~/.dodopayments/config.json.

Khóa mã hóa được tạo từ máy của bạn, vì vậy thông tin xác thực đã lưu chỉ hoạt động trên máy đó. Nếu nâng cấp từ v3.0.x, phiên bản lưu key trong OS keychain, hãy chạy lại dodo login. Các key trong file plaintext cũ ~/.dodopayments/api-key sẽ được tự động di chuyển và file đó bị xóa.

Chuyển mode và đăng xuất

Bạn có thể đăng nhập đồng thời một key ở test mode và một key ở live mode. Để chuyển mode đang hoạt động trong TUI, chạy /switch. Để xóa các key đã lưu:

dodo logout all

/logout

Ở direct mode, truyền test, live hoặc all. Trong TUI, /logout yêu cầu bạn chọn All accounts, Test Mode hoặc Live Mode, sau đó yêu cầu xác nhận.

Cách sử dụng

Bạn có thể sử dụng CLI ở hai mode.

1. TUI tương tác (Khuyến nghị)

Chạy dodo không kèm tham số để mở giao diện tương tác:

dodo

Nhập / để mở bảng lệnh. Văn bản không bắt đầu bằng / sẽ được gửi đến trợ lý AI.

Lệnh	Mô tả
`/help`	Hiển thị tài liệu tham khảo về lệnh
`/update`	Kiểm tra và cài đặt bản cập nhật CLI
`/login`	Xác thực bằng API key
`/logout`	Đăng xuất khỏi một hoặc tất cả môi trường
`/switch`	Chuyển đổi giữa test mode và live mode
`/clear`	Xóa màn hình TUI
`/exit`	Thoát TUI (cũng có thể nhập `exit` hoặc nhấn `Esc` hai lần)

2. Subcommand trực tiếp

Chạy một lệnh mà không mở TUI:

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

Ví dụ:

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

Các bảng tham khảo bên dưới liệt kê mọi lệnh ở dạng direct mode. Trong TUI, thay dodo bằng /, chẳng hạn /payments list 1. Các lệnh được đánh dấu TUI only là các trình hướng dẫn tương tác. Ở direct mode, chúng sẽ in thông báo yêu cầu bạn mở TUI.

Trợ lý AI

Đặt câu hỏi về tài khoản hoặc thực hiện tác vụ bằng tiếng Anh thông thường. Trợ lý chạy dodopayments-mcp trên máy của bạn, nên không cần thiết lập thêm hoặc OAuth flow. Trợ lý gọi Dodo Payments API từ máy của bạn bằng key đã lưu và gửi prompt của bạn đến language model.

Lệnh	Mô tả
`/ai <query>`	Đặt câu hỏi hoặc đưa chỉ thị cho trợ lý AI
(bất kỳ văn bản nào không có dấu gạch chéo)	Mặc định được gửi đến trợ lý AI khi đang ở TUI

Ở direct mode, chạy dodo ai rồi nhập câu hỏi. Ví dụ trong TUI:

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

Trợ lý sử dụng mode đang hoạt động của bạn (test mode hoặc live mode) và chỉ làm việc với dữ liệu của mode đó.

Tạo cấu trúc dự án

dodo init thêm các billing route của Dodo Payments vào dự án hiện có. Lệnh ghi các file route, cài package adapter @dodopayments/* tương ứng và thêm các biến DODO_PAYMENTS_* còn thiếu vào file .env với giá trị placeholder. Lệnh bỏ qua các file và biến đã tồn tại, đồng thời chạy mà không cần đăng nhập.

dodo init <framework>

Scaffold	Mô tả
`dodo init nextjs`	Tạo các billing route cho Next.js App Router (checkout, customer portal và webhook handler) bằng `@dodopayments/nextjs`
`dodo init express`	Tạo các billing route cho Express server bằng `@dodopayments/express`
`dodo init better-auth`	Tạo cấu hình plugin Better-Auth bằng `@dodopayments/better-auth`

Với Better-Auth scaffold, bạn có thể truyền danh sách plugin phân tách bằng dấu phẩy để tạo: checkout, portal, usage và webhooks. Nếu không truyền danh sách, cả bốn plugin sẽ được tạo.

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

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

Nếu dự án có thư mục src/, scaffolder sẽ ghi các file vào đó. Lệnh này chọn install command từ lock file của dự án (bun, pnpm hoặc yarn) và sử dụng npm nếu không tìm thấy lock file.

Tài liệu tham khảo về lệnh

Các lệnh này yêu cầu API key đã đăng nhập. Các lệnh list nhận số trang tùy chọn, mặc định là 1 và hiển thị tối đa 100 mục trên mỗi trang.

Product

Quản lý product catalog.

Lệnh	Mô tả
`dodo products list <page>`	Liệt kê product
`dodo products create`	Mở dashboard để tạo product
`dodo products info <id>`	Xem chi tiết product cụ thể

Payment

Xem các giao dịch payment.

Lệnh	Mô tả
`dodo payments list <page>`	Liệt kê payment
`dodo payments info <id>`	Lấy thông tin về payment cụ thể

Customer

Quản lý customer.

Lệnh	Mô tả
`dodo customers list <page>`	Liệt kê customer
`dodo customers create`	Tạo customer mới (chỉ TUI)
`dodo customers update <id>`	Cập nhật customer hiện có (chỉ TUI)
`dodo customers portal <id>`	Tạo phiên Customer Portal tạm thời cho customer

Discount

Quản lý mã discount.

Lệnh	Mô tả
`dodo discounts list <page>`	Liệt kê discount
`dodo discounts create`	Tạo discount theo phần trăm mới (chỉ TUI)
`dodo discounts delete <id>`	Xóa discount theo ID (chỉ TUI)

License

Xem license key. Lệnh được viết là licences.

Lệnh	Mô tả
`dodo licences list <page>`	Liệt kê license

Addon

Quản lý product add-on.

Lệnh	Mô tả
`dodo addons list <page>`	Liệt kê addon
`dodo addons create`	Mở dashboard để tạo addon
`dodo addons info <id>`	Xem chi tiết addon cụ thể

Refund

Xem thông tin refund.

Lệnh	Mô tả
`dodo refunds list <page>`	Liệt kê refund
`dodo refunds info <id>`	Xem chi tiết refund cụ thể

Checkout

Tạo hosted checkout session.

Lệnh	Mô tả
`dodo checkout new`	Tương tác để tạo hosted checkout session và lấy payment link (chỉ TUI)

Webhook

CLI có hai công cụ webhook dành cho development: listener chuyển tiếp webhook ở test mode đến server cục bộ và trigger gửi payload webhook giả lập đến bất kỳ endpoint nào.

Lệnh	Mô tả
`dodo wh listen <url>`	Lắng nghe webhook theo thời gian thực và chuyển tiếp đến local dev server
`dodo wh trigger <event> <url>`	Gửi sự kiện webhook giả lập, kể cả khi chưa đăng nhập

Ở direct mode, các tham số là bắt buộc. Trong TUI, chạy /wh listen hoặc /wh trigger không kèm tham số để mở trình hướng dẫn tương tác.

Lắng nghe Webhook

Chuyển tiếp webhook từ tài khoản Dodo Payments đến local development server theo thời gian thực.

dodo wh listen yêu cầu API key ở Test Mode. Key ở Live Mode không được hỗ trợ bởi quy trình listen.

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

Enter Your Local Endpoint URL

Truyền local URL sẽ nhận webhook, ví dụ http://localhost:3000/webhook. Trong TUI wizard, CLI sẽ yêu cầu bạn nhập URL này.

Automatic Setup

Nếu tài khoản chưa có webhook endpoint cho relay server của CLI, CLI sẽ tạo một endpoint. Endpoint xuất hiện trong Developer → Webhooks. Sau đó CLI mở kết nối WebSocket đến relay để nhận sự kiện theo thời gian thực.

Receive and Forward

Khi một sự kiện webhook được kích hoạt, chẳng hạn từ payment thử nghiệm hoặc thay đổi subscription, CLI chuyển tiếp payload và header đến local endpoint của bạn dưới dạng request POST. CLI ghi log loại sự kiện và response của endpoint, rồi gửi response trở lại relay.

Listener giữ nguyên các webhook header gốc (webhook-id, webhook-signature, webhook-timestamp) khi chuyển tiếp đến local endpoint, để bạn có thể kiểm thử logic xác minh signature.

Relay và CLI phân tích cú pháp phần thân JSON rồi tuần tự hóa lại trước khi chuyển tiếp. Nếu phần thân được chuyển tiếp khác từng byte so với bản gốc, chẳng hạn như ở định dạng số, quá trình xác minh chữ ký sẽ thất bại dù các header vẫn nguyên vẹn.

Kích hoạt Webhook thử nghiệm

Gửi payload webhook giả lập đến bất kỳ endpoint nào mà không tạo giao dịch thực.

Các sự kiện được trigger không được ký: request không chứa header webhook-id, webhook-signature hoặc webhook-timestamp. Khi kiểm thử, hãy parse chúng bằng method chưa xác minh (unsafeUnwrap trong TypeScript, unsafe_unwrap trong Python, UnsafeUnwrap trong Go) thay vì unwrap, và chuyển lại sang unwrap trước khi chạy production.

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

Ở direct mode, payload sử dụng ID và thông tin customer placeholder. /wh trigger wizard trong TUI hướng dẫn bạn qua các bước:

Thiết lập endpoint URL đích.
Tùy chọn nhập Business ID, Product ID, Metadata (một JSON object), Customer email và Customer ID cho payload. Trường để trống sẽ sử dụng giá trị placeholder.
Chọn event cần gửi từ menu tương tác. Bạn có thể gửi nhiều event liên tiếp. Chọn exit để kết thúc.

dodo wh trigger không yêu cầu đăng nhập. Đây là local, offline webhook payload generator.

Webhook Event được hỗ trợ

dodo wh trigger có thể gửi payload giả lập cho 46 trong số 48 event type mà Dodo Payments cung cấp. Công cụ không hỗ trợ subscription.past_due hoặc subscription.unpaused. Truyền tên event chính xác như danh sách dưới đây:

Danh mục	Event
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`

Ba tên trigger khác với event type trong payload mà chúng gửi: payment.success gửi payment.succeeded, refund.success gửi refund.succeeded và licence.created gửi license_key.created.

Cấu trúc payload giả lập tuân theo schema tương ứng trong API reference. Xem Webhook Events để biết ý nghĩa của từng event và thời điểm Dodo Payments phát ra event đó trong production.

payout.created được phát ra khi payout vẫn có status not_initiated, vì vậy payload giả lập cũng phản ánh điều đó. Xem Payout Events để biết toàn bộ vòng đời payout.

Biến môi trường

Biến này thay đổi cách dodo wh listen kết nối:

Biến	Mô tả
`DODO_WH_TEST_SERVER_URL`	Ghi đè webhook relay server mặc định được `dodo wh listen` sử dụng. Đặt tên host không kèm scheme.

Cập nhật

CLI kiểm tra phiên bản mới hơn khi khởi động và hiển thị thông báo trên status bar khi có phiên bản mới. Để nâng cấp bản cài đặt npm hoặc Bun từ TUI, chạy:

/update

/update không thể nâng cấp binary của bản phát hành. Với các bản cài đặt binary, bao gồm bản cài bằng install script, lệnh này thay vào đó liên kết đến GitHub release mới nhất. Để nâng cấp từ shell, chạy lại lệnh bạn đã dùng để cài đặt:

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

npm install -g dodopayments-cli

bun install -g dodopayments-cli

Tài nguyên

GitHub Repository

Mã nguồn và các bản phát hành.

npm Package

Package dodopayments-cli trên npm registry.

Hỗ trợ

Discord: Tham gia community server.
GitHub: Mở issue trên repository.
Email: Liên hệ support@dodopayments.com.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Tính năng

Cài đặt

Cài đặt bằng NPM hoặc Bun

Cài đặt thủ công (Không cần Node / Bun)

Xác thực

Chuyển mode và đăng xuất

Cách sử dụng

1. TUI tương tác (Khuyến nghị)

2. Subcommand trực tiếp

Trợ lý AI

Tạo cấu trúc dự án

Tài liệu tham khảo về lệnh

Product

Payment

Customer

Discount

License

Addon

Refund

Checkout

Webhook

Lắng nghe Webhook

Kích hoạt Webhook thử nghiệm

Webhook Event được hỗ trợ

Biến môi trường

Cập nhật

Tài nguyên

GitHub Repository

npm Package

Hỗ trợ

​Tính năng

​Cài đặt

​Cài đặt bằng NPM hoặc Bun

​Cài đặt thủ công (Không cần Node / Bun)

​Xác thực

​Chuyển mode và đăng xuất

​Cách sử dụng

​1. TUI tương tác (Khuyến nghị)

​2. Subcommand trực tiếp

​Trợ lý AI

​Tạo cấu trúc dự án

​Tài liệu tham khảo về lệnh

​Product

​Payment

​Customer

​Discount

​License

​Addon

​Refund

​Checkout

​Webhook

​Lắng nghe Webhook

​Kích hoạt Webhook thử nghiệm

​Webhook Event được hỗ trợ

​Biến môi trường

​Cập nhật

​Tài nguyên

GitHub Repository

npm Package

​Hỗ trợ

Tính năng

Cài đặt

Cài đặt bằng NPM hoặc Bun

Cài đặt thủ công (Không cần Node / Bun)

Xác thực

Chuyển mode và đăng xuất

Cách sử dụng

1. TUI tương tác (Khuyến nghị)

2. Subcommand trực tiếp

Trợ lý AI

Tạo cấu trúc dự án

Tài liệu tham khảo về lệnh

Product

Payment

Customer

Discount

License

Addon

Refund

Checkout

Webhook

Lắng nghe Webhook

Kích hoạt Webhook thử nghiệm

Webhook Event được hỗ trợ

Biến môi trường

Cập nhật

Tài nguyên

Hỗ trợ