Core commands

The CLI's core commands set up and control the CLI, like logging in, choosing your sandbox or live account, changing settings, and calling an API endpoint directly.

This page also covers global flags, environment variables, and config keys. They work with every command, including resource commands.

Run paddle --help to see every command, or paddle <command> --help for details on one.

For commands that work with Paddle entities, like products and subscriptions, see Resource commands.

Log in

Use these commands to log in to and out of Paddle, and check which account you're logged in to. For an overview of logging in, see Log in.

`paddle login`

Shell

paddle login --environment sandbox --api-key YOUR_API_KEY     # sandbox account, with an API key
paddle login --environment production --api-key YOUR_API_KEY  # live account, with an API key
paddle login --environment production                         # live account, with OAuth
paddle login --api-key YOUR_API_KEY                           # default account, with an API key

paddle login takes these flags:

Flag	Description
`--api-key <key>`	The API key to save.
`--environment <env>`	The account to log in to: `sandbox` or `production`. Defaults to the account you last switched to or logged in to, or `production` if you haven't done either.
`--agent`	For OAuth, print the login link instead of opening a browser.

With --api-key, the CLI checks the key is valid with Paddle before saving it. Without --api-key, the CLI opens your browser so you can log in with OAuth. OAuth is only available for live accounts.

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

`paddle logout`

Remove saved logins for the account you're using.

Shell

paddle logout

`paddle whoami`

Show which account you're logged in to, your seller ID, and the scopes your login has.

Shell

paddle whoami

Choose an account

Use these commands to check which account you're using, and switch between your sandbox and live accounts.

`paddle environment`

Show which account you're using and the API URL the CLI sends requests to.

Shell

paddle environment

`paddle sandbox` and `paddle production`

Switch to your sandbox or live account. Your choice is saved until you change it.

Shell

paddle sandbox
paddle production

`paddle switch`

Switch to an account by name. paddle switch sandbox is the same as paddle sandbox.

Shell

paddle switch production

To use a different account for one command without switching, pass the --environment global flag.

Settings

Use these commands to view and change the settings the CLI saves, like your default output format.

`paddle config`

View or change settings in the CLI config file.

Shell

paddle config list                         # show every setting and its value
paddle config get default_output           # show your default output format
paddle config set default_output json      # change it to JSON
paddle config unset default_output         # change it back to the default

You can change these settings with paddle config set:

Key	Values	Description
`default_output`	`table`, `json`, `csv`	The output format to use when you don't pass `--output`.
`color`	`auto`, `always`, `never`	Whether to use colors. `auto` uses colors in a terminal, not when output is sent to a file or another program.
`api_version`	An API version, like `1`	The Paddle API version to send with requests.

`paddle output`

Set the default output format. paddle output json is the same as paddle config set default_output json.

Shell

paddle output json

Other commands

Use these commands to send requests directly to any API endpoint, set up tab completion, and get the CLI version or help.

`paddle api`

Send a request to any Paddle API endpoint with the saved login for the account you're using. Use it for endpoints that don't have a resource command yet.

Pass a path with the command, like /products. Full URLs aren't accepted.

Shell

paddle api /event-types                                           # list event types
paddle api /customers --query status=active --query per_page=10   # list active customers, 10 per page
paddle api /products --method POST --json @product.json           # create a product from a JSON file

paddle api takes these flags:

Flag	Description
`--method <method>`	The HTTP method: `GET`, `POST`, `PATCH`, or `DELETE`. Defaults to `GET`.
`--json <body>`	The request body sent as JSON. Pass it inline, from a file with `@file.json`, or from stdin with `-`.
`--query <key=value>`	A query parameter. Repeat to add more than one parameter. Overrides any query string in the path.

`paddle completion`

Set up tab completion for your shell. When you type part of a command or flag and press Tab, your shell fills in the rest. Supports bash, zsh, fish, and powershell.

Shell

paddle completion zsh --help    # show how to set up tab completion for zsh

`paddle version`

Show the installed CLI version.

Shell

paddle version

`paddle help`

Show help for any command or resource, or read about a topic. paddle help products is the same as paddle products --help.

Shell

paddle help products           # view commands for products
paddle help products create    # view fields for creating a product
paddle help exit-codes         # view help for exit codes

You can read about these topics:

Topic	Covers
`environment`	Sandbox and live accounts, and how the CLI chooses which one to use.
`exit-codes`	What each exit code means.
`formatting`	Output formats and how the CLI chooses one.
`api-versions`	Choosing a Paddle API version.

Global flags

You can pass these flags to any command. Most can also be set with an environment variable or a config key. If you set more than one, the flag takes priority, then the environment variable, then the config key.

Flag	Environment variable	Config key	Description
`--api-key <key>`	`PADDLE_API_KEY`	—	The API key to use. Overrides the key saved with `paddle login`.
`--environment <env>`	`PADDLE_ENVIRONMENT`	—	The account to use for this command: `sandbox` or `production`. Doesn't change your saved choice.
`-o`, `--output <fmt>`	`PADDLE_OUTPUT`	`default_output`	Output format: `table`, `json`, or `csv`.
`--jq <expr>`	—	—	Filter or reshape the output with a jq expression.
`--agent`	`PADDLE_AGENT=1`	—	Turn on agent mode.
`--api-version <ver>`	`PADDLE_API_VERSION`	`api_version`	The Paddle API version to use.
`--header 'Key: Value'`	`PADDLE_HEADER`	—	Add a custom HTTP header. Repeat the flag for more than one. The environment variable takes a comma-separated list.
`--non-interactive`	—	—	Don't show prompts. Doesn't change the output format.
`--no-banner`	`PADDLE_NO_BANNER=1`	`no_banner`	Don't print which account the command used, like `→ sandbox`, after each command.
`--no-color`	`NO_COLOR`	`color`	Don't use colors.

Environment variables

These environment variables don't have a matching flag:

Variable	Description
`PADDLE_NO_KEYCHAIN`	Set to `1` to store credentials in the config file instead of the macOS Keychain.
`FORCE_COLOR`	Set to use colors even when output isn't going to a terminal.

Config file

The CLI saves your settings in a config file:

macOS and Linux: ~/.config/paddle/config.yaml
Windows: %USERPROFILE%\.config\paddle\config.yaml

Use paddle config to change settings, rather than editing the file.

To hide which account each command used, like → sandbox, add no_banner: true to the config file. You can't set it with paddle config set.

You can also hide it for one terminal session with PADDLE_NO_BANNER=1, or for one command with --no-banner.

Core commands

Log in

paddle login

paddle logout

paddle whoami

Choose an account

paddle environment

paddle sandbox and paddle production

paddle switch

Settings

paddle config

paddle output

Other commands

paddle api

paddle completion

paddle version

paddle help

Global flags

Environment variables

Config file

Was this page helpful?

`paddle login`

`paddle logout`

`paddle whoami`

`paddle environment`

`paddle sandbox` and `paddle production`

`paddle switch`

`paddle config`

`paddle output`

`paddle api`

`paddle completion`

`paddle version`

`paddle help`