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

# Core commands

Core Paddle CLI commands that handle login, settings, and raw API requests, plus global flags, environment variables, and config keys.

---

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](https://developer.paddle.com/sdks/cli/resource-commands.md).

## 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](https://developer.paddle.com/sdks/cli.md#log-in).

### `paddle login`

Log in to your sandbox or live account and save your login:

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

```sh
paddle logout
```

### `paddle whoami`

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

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

```sh
paddle environment
```

### `paddle sandbox` and `paddle production`

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

```sh
paddle sandbox
paddle production
```

### `paddle switch`

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

```sh
paddle switch production
```

To use a different account for one command without switching, pass the `--environment` [global flag](#global-flags).

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

```sh
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](https://developer.paddle.com/api-reference/about/versioning.md) to send with requests. |

### `paddle output`

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

```sh
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](https://developer.paddle.com/api-reference.md) 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.

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

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

### `paddle version`

Show the installed CLI version.

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

```sh
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](https://developer.paddle.com/sdks/cli/scripting-and-agents.md#exit-codes) 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](https://jqlang.org) expression.                    |
| `--agent`               | `PADDLE_AGENT=1`              | —                | Turn on [agent mode](https://developer.paddle.com/sdks/cli/scripting-and-agents.md#agent-mode).                            |
| `--api-version <ver>`   | `PADDLE_API_VERSION`          | `api_version`    | The [Paddle API version](https://developer.paddle.com/api-reference/about/versioning.md) 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:
{% definition-list %}
{% definition term="macOS and Linux" %}
`~/.config/paddle/config.yaml`
{% /definition %}
{% definition term="Windows" %}
`%USERPROFILE%\\.config\\paddle\\config.yaml`
{% /definition %}
{% /definition-list %}
Use [`paddle config`](#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`.