> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Paddle CLI

Work with the Paddle API from your terminal, in scripts and CI/CD pipelines, or through your AI agents. Install the Paddle CLI, log in, and choose your account.

---

{% version-badge sdk="paddle-cli" /%}

The Paddle CLI is a command-line tool for the Paddle API. Use it to work with products, prices, customers, subscriptions, transactions, and more from your terminal, in scripts, and in CI/CD pipelines.

The CLI is designed for people and AI agents alike. Turn a task into a set of commands once and rerun it yourself, in a scheduled routine, or with an AI agent.

[View the Paddle CLI on GitHub](https://github.com/PaddleHQ/paddle-cli)

## How it works

The Paddle CLI has two kinds of commands:

- **[Resource commands](https://developer.paddle.com/sdks/cli/resource-commands.md)** work with entities in your Paddle account, like products and subscriptions. They match the operations in the [Paddle API](https://developer.paddle.com/api-reference.md). For example, `paddle products create` sends the same request as [create a product](https://developer.paddle.com/api-reference/products/create-product.md).
- **[Core commands](https://developer.paddle.com/sdks/cli/commands.md)** manage how the CLI works, like your login, which account you're using, and your settings.

## Install

{% tabs sync="cli-install-os" %}
{% tab-item title="macOS" %}

You can install the Paddle CLI using [Homebrew](#homebrew), the [install script](#install-script), or a [manual download](#download-manually). You can also [build from source](#build-from-source).

### Homebrew

Install `paddlehq/tap/paddle` with [Homebrew](https://brew.sh):

```sh
brew install paddlehq/tap/paddle
```

### Install script

The install script downloads the latest release for your system, checks it against the release's checksums, and installs `paddle` in `/usr/local/bin`. If you can't write to `/usr/local/bin`, it installs `paddle` in `~/.local/bin` instead. If that folder isn't on your `PATH`, the script tells you.

```sh
curl -fsSL https://raw.githubusercontent.com/PaddleHQ/paddle-cli/main/install.sh | sh
```

To install a specific version or choose the folder, pass options after `sh -s --`:

```sh
curl -fsSL https://raw.githubusercontent.com/PaddleHQ/paddle-cli/main/install.sh | sh -s -- --version vX.Y.Z --dir ~/bin
```

You can also set the `PADDLE_INSTALL_VERSION` and `PADDLE_INSTALL_DIR` environment variables.

### Download manually

1. Download the `.tar.gz` archive for your Mac from the [latest release on GitHub](https://github.com/PaddleHQ/paddle-cli/releases/latest). Choose the Apple silicon (`arm64`) or Intel (`amd64`) version.
2. Optionally, verify the archive against `checksums.txt` from the same release.
3. Extract the archive. It contains the `paddle` binary.
4. Move `paddle` to a folder on your `PATH`, like `/usr/local/bin`:

   ```sh
   sudo mv paddle /usr/local/bin/
   ```

5. If macOS blocks `paddle` from running, remove the quarantine flag that macOS adds to downloaded files:

   ```sh
   xattr -d com.apple.quarantine /usr/local/bin/paddle
   ```

{% /tab-item %}
{% tab-item title="Linux" %}

You can install the Paddle CLI using the [install script](#install-script-linux), [Homebrew](#homebrew-linux), or a [manual download](#download-manually-linux). You can also [build from source](#build-from-source).

### Install script {% id="install-script-linux" %}

The install script downloads the latest release for your system, checks it against the release's checksums, and installs `paddle` in `/usr/local/bin`. If you can't write to `/usr/local/bin`, it installs `paddle` in `~/.local/bin` instead. If that folder isn't on your `PATH`, the script tells you.

```sh
curl -fsSL https://raw.githubusercontent.com/PaddleHQ/paddle-cli/main/install.sh | sh
```

To install a specific version or choose the folder, pass options after `sh -s --`:

```sh
curl -fsSL https://raw.githubusercontent.com/PaddleHQ/paddle-cli/main/install.sh | sh -s -- --version vX.Y.Z --dir ~/bin
```

You can also set the `PADDLE_INSTALL_VERSION` and `PADDLE_INSTALL_DIR` environment variables.

### Homebrew {% id="homebrew-linux" %}

Install `paddlehq/tap/paddle` with [Homebrew](https://brew.sh):

```sh
brew install paddlehq/tap/paddle
```

### Download manually {% id="download-manually-linux" %}

1. Download the `.tar.gz` archive for your system from the [latest release on GitHub](https://github.com/PaddleHQ/paddle-cli/releases/latest). Choose `amd64` for Intel and AMD processors, or `arm64` for ARM processors.
2. Optionally, verify the archive against `checksums.txt` from the same release.
3. Extract the archive. It contains the `paddle` binary.
4. Move `paddle` to a folder on your `PATH`, like `/usr/local/bin`:

   ```sh
   sudo mv paddle /usr/local/bin/
   ```

{% /tab-item %}
{% tab-item title="Windows" %}

Download the Paddle CLI from GitHub:

1. Download the Windows `.zip` archive for your processor, `amd64` or `arm64`, from the [latest release on GitHub](https://github.com/PaddleHQ/paddle-cli/releases/latest).
2. Optionally, verify the archive against `checksums.txt` from the same release.
3. Extract `paddle.exe` from the archive.
4. Move `paddle.exe` to a permanent folder, then add that folder to your `PATH` so you can run `paddle` from any folder.
5. Open a new terminal, like PowerShell or Command Prompt, before running any `paddle` commands. Terminals that were already open won't find `paddle`.

{% callout type="info" %}
Don't double-click `paddle.exe`, because the window opens and closes right away. Run `paddle` commands from a terminal instead.
{% /callout %}

You can also run the Linux version using [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/windows/wsl/install).

{% /tab-item %}
{% /tabs %}

### Build from source {% id="build-from-source" %}

On macOS and Linux, you can build the CLI from source. You'll need Go 1.26 or later.

Clone the repository, build the CLI, then add it to your `PATH`:

```sh
git clone https://github.com/PaddleHQ/paddle-cli.git
cd paddle-cli
make build
make install-local-build
```

`make install-local-build` links the CLI into `/usr/local/bin`, letting you run `paddle` from any folder. The link points to the `paddle-cli` folder. Don't move or delete that folder after you install.

To link the CLI into a different folder, set `INSTALL_DIR`:

```sh
make install-local-build INSTALL_DIR=~/.local/bin
```

### Check the installation

Check that the CLI is installed:

```sh
paddle --version
```

## Log in

Unless you've switched to or logged in to your sandbox account, the CLI uses your live account for `paddle login` and every other command. To log in to your sandbox account, add `--environment sandbox`, or run `paddle sandbox` first.

How you log in depends on the account:

| Account | Authentication   |
| ------- | ---------------- |
| Sandbox | API key          |
| Live    | OAuth or API key |

The CLI saves one login for each account, so you can be logged in to your sandbox and live accounts at the same time.

To check that you're logged in, and to which account, run `paddle whoami`.

To log out of the account you're using, run `paddle logout`.

### Log in with OAuth

You can log in to your live account with OAuth. Because the CLI starts in your live account, run:

```sh
paddle login
```

If you've switched to your sandbox account, run `paddle login --environment production` instead.

The CLI opens Paddle in your browser. Log in, then approve access for the Paddle CLI. When you see the success message, close the window and go back to your terminal.

If the CLI can't open a browser, it prints a link instead. Open the link in a browser on the same computer to log in.

OAuth gives the CLI read and write access that matches what your Paddle user role allows. To give an AI agent or CI pipeline more limited access, log in with an [API key](#log-in-with-an-api-key) that has only the [permissions](https://developer.paddle.com/api-reference/about/permissions.md) it needs.

OAuth isn't available for sandbox accounts. Running `paddle login` without an API key in your sandbox account returns an error.

### Log in with an API key

Pass your sandbox or live [Paddle API key](https://developer.paddle.com/api-reference/about/authentication.md#create-an-api-key) to `paddle login`, replacing `YOUR_API_KEY` with your key:

```sh
paddle login --environment sandbox --api-key YOUR_API_KEY    # sandbox account
paddle login --environment production --api-key YOUR_API_KEY # live account
```

The CLI checks your key with Paddle, then saves it for that account. It replaces any login you already had for that account, including an [OAuth login](https://developer.paddle.com/sdks/cli.md#log-in-with-oauth).

Keys only work for their own account. Sandbox keys contain `_sdbx`, and live keys contain `_live`. If the key doesn't match the account, the login fails.

To use a key without saving it, add `--api-key` to any command or set `PADDLE_API_KEY`. This is useful in [CI pipelines](https://developer.paddle.com/sdks/cli/scripting-and-agents.md#cli-in-cicd-pipelines). A key passed this way takes priority over a saved login.

### Where credentials are stored

{% tabs sync="cli-install-os" %}
{% tab-item title="macOS" %}

The CLI saves your login in your Keychain, under the service name `paddle-cli`.

To save your login in the config file instead, set `PADDLE_NO_KEYCHAIN=1` when you log in:

```sh
PADDLE_NO_KEYCHAIN=1 paddle login --environment sandbox --api-key YOUR_API_KEY
```

{% /tab-item %}
{% tab-item title="Linux" %}

The CLI saves your login in plain text in the config file, `~/.config/paddle/config.yaml`. Only your user on this computer can read it. The CLI warns you about this when you log in.

On shared machines or in CI pipelines, [use an API key without saving it](https://developer.paddle.com/sdks/cli/scripting-and-agents.md#cli-in-cicd-pipelines) instead.

{% /tab-item %}
{% tab-item title="Windows" %}

The CLI saves your login in plain text in the config file, `.config\paddle\config.yaml` in your user folder. The CLI warns you about this when you log in.

On shared computers or in CI pipelines, [use an API key without saving it](https://developer.paddle.com/sdks/cli/scripting-and-agents.md#cli-in-cicd-pipelines) instead.

{% /tab-item %}
{% /tabs %}

## Switch accounts

In the CLI, your sandbox account is `sandbox`, and your live account is `production`. Switch between them, or use `--environment` for one command only:

```sh
paddle sandbox                                  # use your sandbox account
paddle production                               # use your live account
paddle products list --environment production   # use your live account for one command
```

Your choice is saved until you change it. For more account commands, see [Core commands](https://developer.paddle.com/sdks/cli/commands.md#choose-an-account).

After each command, the CLI prints the account it used. `→ sandbox` is displayed in yellow, and `→ production` is bright red.

```text
$ paddle products list
ID                               NAME            STATUS
pro_01h7zcgmdc6tmwtjehp3sh7azf   AeroEdit Pro    active
→ sandbox
```

{% callout type="warning" %}
Commands run against your live account change real data. Test in your sandbox account first.
{% /callout %}

## Update

The CLI doesn't automatically check for updates or notify you when a new version is available. Update regularly to get new commands and support for new Paddle API features.

| Installed with    | How to update                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Homebrew          | Run `brew upgrade paddlehq/tap/paddle`.                                                                                              |
| Install script    | Run the [install script](#install-script) again. It installs the latest version.                                                     |
| Manual download   | Download the latest version from the [releases page](https://github.com/PaddleHQ/paddle-cli/releases) and replace your existing one. |
| Build from source | Run `git pull` and `make build` in the `paddle-cli` folder.                                                                          |

## Uninstall

Uninstalling the CLI doesn't remove your saved logins or settings. To remove everything:

1. Log out of each account. This removes saved API keys, including from your macOS Keychain:

   ```sh
   paddle logout --environment sandbox
   paddle logout --environment production
   ```

2. Uninstall the CLI:

   | Installed with                    | How to uninstall                                                                              |
   | --------------------------------- | --------------------------------------------------------------------------------------------- |
   | Homebrew                          | Run `brew uninstall paddlehq/tap/paddle`.                                                     |
   | Install script or manual download | Delete `paddle` from the folder you installed it in, like `/usr/local/bin` or `~/.local/bin`. |
   | Build from source                 | Run `make uninstall-local-build` in the `paddle-cli` folder, then delete the folder.          |

3. Delete the CLI config folder: `~/.config/paddle`, or `.config\paddle` in your user folder on Windows.