> ## 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

> The official command-line interface for Dodo Payments — manage resources, run AI-powered queries, create checkout sessions, and test webhooks from your terminal.

Manage your Dodo Payments resources, run AI-powered queries against your account, create checkout sessions, and test webhooks — all from the terminal. The CLI ships with an interactive TUI, a built-in AI assistant powered by MCP, and offline webhook testing.

<Frame>
  <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 />
</Frame>

## Features

* **Interactive TUI** — launch `dodo` with no arguments to open the full interactive interface with command palette, history, and live notifications.
* **AI assistant built in** — ask questions or take actions in plain English with `/ai`. No extra setup, runs `dodopayments-mcp` locally.
* **Secure by default** — API keys are stored in your OS secret store (macOS Keychain, Windows Credential Vault, Linux libsecret). No plaintext config on disk.
* **Auto update** — the CLI checks for new versions on startup and notifies you in-app. Run `/update` to upgrade in place.
* **Webhook tooling** — listen for live webhooks or trigger payloads offline for local development.

## Installation

Install the CLI in one line on macOS or Linux:

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

### Install with npm or Bun

If you already have Node or Bun, the package-manager installs always pull the latest version:

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

  ```bash Bun theme={null}
  bun install -g dodopayments-cli
  ```
</CodeGroup>

### Manual installation (no Node / Bun required)

If you'd rather not pipe a remote script to `sh`, download the binary yourself.

<Steps>
  <Step title="Download the binary">
    Download the binary for your platform from the latest [GitHub Release](https://github.com/dodopayments/dodopayments-cli/releases).

    | Platform              | 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` |
  </Step>

  <Step title="Rename the binary to `dodo`">
    <CodeGroup>
      ```bash Linux / macOS theme={null}
      mv ./dodo-cli-* ./dodo && chmod +x ./dodo
      ```

      ```powershell Windows theme={null}
      ren .\dodo-cli-windows-x64.exe .\dodo.exe
      ```
    </CodeGroup>
  </Step>

  <Step title="Move it to a directory on your PATH">
    <CodeGroup>
      ```bash Linux / macOS theme={null}
      sudo mv ./dodo /usr/local/bin/
      ```

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

    <Info>
      On Windows, moving to `C:\Windows\System32` requires administrator privileges.
    </Info>
  </Step>

  <Step title="(Optional) Verify the download">
    Each release publishes a `SHA256SUMS.txt`. Verify your download with:

    ```bash theme={null}
    shasum -a 256 -c SHA256SUMS.txt
    ```
  </Step>
</Steps>

## Authentication

Before using authenticated commands, log in with your API key:

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

Or, from inside the interactive TUI:

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

The login flow will:

1. Open your browser to the Dodo Payments API Keys page.
2. Prompt you to paste your API Key.
3. Ask you to select an environment — **Test Mode** or **Live Mode**.
4. Store the credentials in your OS secret store (Keychain on macOS, Credential Vault on Windows, libsecret on Linux).

<Info>
  Because credentials are stored in the OS secret store, you may be prompted for your **device password** the first time the CLI reads or writes credentials. If you're upgrading from an older version, any existing plaintext API key will be **migrated to the secret store and the legacy file deleted** automatically.
</Info>

### Switching modes and logging out

You can keep one **Test Mode** and one **Live Mode** key authenticated at the same time. To clear credentials:

<CodeGroup>
  ```bash Direct theme={null}
  dodo logout
  ```

  ```text TUI theme={null}
  /logout
  ```
</CodeGroup>

The logout flow lets you choose between **All accounts**, **Test Mode**, or **Live Mode** independently.

## Usage

You can use the CLI in two modes.

### 1. Interactive TUI (recommended)

Run `dodo` with no arguments to launch the full interactive interface:

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

Type `/` to open the command palette, or just start typing — anything that isn't a slash command is sent to the AI assistant.

| Command   | Description                                            |
| --------- | ------------------------------------------------------ |
| `/help`   | Show the command reference                             |
| `/update` | Check for and install a CLI update                     |
| `/login`  | Authenticate with an API key                           |
| `/logout` | Sign out of one or all environments                    |
| `/clear`  | Clear the TUI screen                                   |
| `/exit`   | Exit the TUI (also: type `exit`, or press `Esc` twice) |

### 2. Direct subcommands

Run commands directly without entering the TUI:

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

For example:

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

The reference tables below show every command. In the TUI, prefix them with `/`; in direct mode, drop the `/`.

## AI Assistant

Ask questions or take actions in natural language. The assistant uses `dodopayments-mcp` running locally — no additional setup or OAuth flow required, and your AI traffic doesn't leave your machine except to talk to the model provider.

| Command                | Description                                               |
| ---------------------- | --------------------------------------------------------- |
| `/ai <query>`          | Ask the AI assistant a question or give it an instruction |
| *(any non-slash text)* | Sent to the AI assistant by default while in the TUI      |

Examples:

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

<Tip>
  The assistant respects your active environment (Test / Live), so it only operates on data from the environment you're currently logged into.
</Tip>

## Project Scaffolding

`dodo init` scaffolds Dodo Payments billing routes directly into an existing project. It generates the boilerplate route files, installs the matching `@dodopayments/*` adapter package, and safely writes the `DODO_PAYMENTS_*` environment variables to your `.env` (it only appends variables that aren't already present). The command runs **without logging in**.

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

| Scaffold                | Description                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `dodo init nextjs`      | Scaffold Next.js App Router billing routes (checkout, customer portal, and webhook handlers) using `@dodopayments/nextjs` |
| `dodo init express`     | Scaffold Express server billing routes using `@dodopayments/express`                                                      |
| `dodo init better-auth` | Scaffold a Better-Auth plugin configuration using `@dodopayments/better-auth`                                             |

For the Better-Auth scaffold you can pass a comma-separated list of plugins to generate (defaults to all): `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
```

<Info>
  The scaffolder auto-detects a `src/` directory and adjusts output paths accordingly, and auto-detects your package manager (`bun`, `pnpm`, `yarn`, or `npm`) to run the correct install command.
</Info>

## Command Reference

### Products

Manage your product catalog.

| Command                     | Description                            |
| --------------------------- | -------------------------------------- |
| `dodo products list <page>` | List products                          |
| `dodo products create`      | Open the dashboard to create a product |
| `dodo products info <id>`   | View details for a specific product    |

### Payments

View payment transactions.

| Command                     | Description                              |
| --------------------------- | ---------------------------------------- |
| `dodo payments list <page>` | List payments                            |
| `dodo payments info <id>`   | Get information about a specific payment |

### Customers

Manage your customer base.

| Command                      | Description                 |
| ---------------------------- | --------------------------- |
| `dodo customers list <page>` | List customers              |
| `dodo customers create`      | Create a new customer       |
| `dodo customers update <id>` | Update an existing customer |

### Discounts

Manage coupons and discounts.

| Command                      | Description                            |
| ---------------------------- | -------------------------------------- |
| `dodo discounts list <page>` | List discounts                         |
| `dodo discounts create`      | Create a new percentage-based discount |
| `dodo discounts delete <id>` | Remove a discount by ID                |

### Licenses

Manage software licenses.

| Command                     | Description   |
| --------------------------- | ------------- |
| `dodo licences list <page>` | List licenses |

### Addons

Manage product addons.

| Command                   | Description                           |
| ------------------------- | ------------------------------------- |
| `dodo addons list <page>` | List addons                           |
| `dodo addons create`      | Open the dashboard to create an addon |
| `dodo addons info <id>`   | View details for a specific addon     |

### Refunds

View refund information.

| Command                    | Description                        |
| -------------------------- | ---------------------------------- |
| `dodo refunds list <page>` | List refunds                       |
| `dodo refunds info <id>`   | View details for a specific refund |

### Checkout

Create hosted checkout sessions.

| Command             | Description                                                           |
| ------------------- | --------------------------------------------------------------------- |
| `dodo checkout new` | Interactively create a hosted checkout session and get a payment link |

## Webhooks

The CLI includes two powerful tools for testing webhooks during development: a **listener** that forwards live test webhooks to your local server, and a **trigger** that sends mock webhook payloads to any endpoint.

| Command           | Description                                                                |
| ----------------- | -------------------------------------------------------------------------- |
| `dodo wh listen`  | Listen for webhooks in real time and forward them to your local dev server |
| `dodo wh trigger` | Trigger a test webhook event interactively — even while logged out         |

### Listen for webhooks

Forward webhooks from Dodo Payments directly to your local development server in real time.

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

<Steps>
  <Step title="Enter your local endpoint URL">
    Provide the local URL where you want to receive webhooks (e.g., `http://localhost:3000/webhook`).
  </Step>

  <Step title="Automatic setup">
    The CLI automatically creates a webhook endpoint on your Dodo Payments account if one doesn't already exist, then opens a WebSocket connection to receive events in real time.
  </Step>

  <Step title="Receive and forward">
    When a webhook event fires (from a test payment, subscription change, etc.), the CLI receives it, logs the event type, and forwards the full request with headers and body to your local endpoint. The response from your endpoint is logged and sent back.
  </Step>
</Steps>

<Warning>
  `dodo wh listen` requires a **Test Mode** API key. Live Mode keys are not supported by the listen flow.
</Warning>

<Tip>
  The listener preserves the original webhook headers (`webhook-id`, `webhook-signature`, `webhook-timestamp`) when forwarding to your local endpoint, so you can test your signature verification logic.
</Tip>

### Trigger test webhooks

Send mock webhook payloads to any endpoint for quick testing without needing to create real transactions.

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

The `/wh trigger` flow guides you through:

1. Setting a destination **endpoint URL**
2. Selecting a specific **event** to trigger from an interactive menu

<Info>
  `dodo wh trigger` does **not** require login. It works as a local/offline webhook payload generator.
</Info>

<Warning>
  Triggered events are **not signed**. While testing, disable webhook signature verification on your endpoint — for example, use `unsafe_unwrap()` instead of `unwrap()` in your webhook handler **during testing only**.
</Warning>

### Supported webhook events

| Category         | Events                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------- |
| **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`                                                                                   |

### Environment variables

| Variable                  | Description                                                            |
| ------------------------- | ---------------------------------------------------------------------- |
| `DODO_WH_TEST_SERVER_URL` | Override the default webhook relay server URL used by `dodo wh listen` |

## Updates

The CLI checks for a newer version on startup and surfaces a notification in the status bar when one is available. To upgrade:

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

Or, re-run the installer to upgrade in place:

<CodeGroup>
  ```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
  ```
</CodeGroup>

## Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/dodopayments-cli">
    View source code and releases
  </Card>

  <Card title="npm Package" icon="npm" href="https://www.npmjs.com/package/dodopayments-cli">
    View on npm registry
  </Card>
</CardGroup>

## Support

* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-cli/issues)
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)