For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Paddle Docs home

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.

AI summary

The Paddle CLI is a command-line tool that lets you manage Paddle API resources like products, subscriptions, and transactions from your terminal, scripts, CI/CD pipelines, and AI agents.

  • •Install via Homebrew, an install script, manual download, or build from source on macOS, Linux, or Windows
  • •Authenticate using an API key for sandbox or live accounts, or OAuth for live accounts only—the CLI supports maintaining separate logins for both environments
  • •Run resource commands that map directly to Paddle API operations (like paddle products create) and core commands for account and credential management
Latest: v0.1.0 · 2026-10-15

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

How it works

The Paddle CLI has two kinds of commands:

  • Resource commands work with entities in your Paddle account, like products and subscriptions. They match the operations in the Paddle API. For example, paddle products create sends the same request as create a product.
  • Core commands manage how the CLI works, like your login, which account you're using, and your settings.

Install

You can install the Paddle CLI using Homebrew, the install script, or a manual download. You can also build from source.

Homebrew

Install paddlehq/tap/paddle with Homebrew:

Shell
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.

Shell
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 --:

Shell
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. 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:

    Shell
    sudo mv paddle /usr/local/bin/

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

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

You can install the Paddle CLI using the install script, Homebrew, or a manual download. You can also build from source.

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.

Shell
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 --:

Shell
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

Install paddlehq/tap/paddle with Homebrew:

Shell
brew install paddlehq/tap/paddle

Download manually

  1. Download the .tar.gz archive for your system from the latest release on GitHub. 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:

    Shell
    sudo mv paddle /usr/local/bin/

Download the Paddle CLI from GitHub:

  1. Download the Windows .zip archive for your processor, amd64 or arm64, from the latest release on GitHub.
  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.

Don't double-click paddle.exe, because the window opens and closes right away. Run paddle commands from a terminal instead.

You can also run the Linux version using Windows Subsystem for Linux (WSL).

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:

Shell
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:

Shell
make install-local-build INSTALL_DIR=~/.local/bin

Check the installation

Check that the CLI is installed:

Shell
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:

AccountAuthentication
SandboxAPI key
LiveOAuth 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:

Shell
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 that has only the permissions 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 to paddle login, replacing YOUR_API_KEY with your key:

Shell
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.

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. A key passed this way takes priority over a saved login.

Where credentials are stored

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:

Shell
PADDLE_NO_KEYCHAIN=1 paddle login --environment sandbox --api-key YOUR_API_KEY

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 instead.

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 instead.

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:

Shell
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.

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

Commands run against your live account change real data. Test in your sandbox account first.

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 withHow to update
HomebrewRun brew upgrade paddlehq/tap/paddle.
Install scriptRun the install script again. It installs the latest version.
Manual downloadDownload the latest version from the releases page and replace your existing one.
Build from sourceRun 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:

    Shell
    paddle logout --environment sandbox
    paddle logout --environment production

  2. Uninstall the CLI:

    Installed withHow to uninstall
    HomebrewRun brew uninstall paddlehq/tap/paddle.
    Install script or manual downloadDelete paddle from the folder you installed it in, like /usr/local/bin or ~/.local/bin.
    Build from sourceRun 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.

Was this page helpful?