# Stripe CLI Reference

This reference documents every command and flag available in Stripe’s command-line interface. The Stripe CLI helps you build, test, and manage your Stripe integration right from the terminal. With the CLI, you can:

* Create, retrieve, update, and delete [API objects](https://docs.stripe.com/cli/resources.md).
* [Tail API request logs](https://docs.stripe.com/cli/logs/tail.md) in real time.
* [Securely test webhooks](https://docs.stripe.com/cli/listen.md) without relying on third-party tunneling software.

Follow the [installation guide](https://docs.stripe.com/stripe-cli.md#install) to set up the Stripe CLI.

## Core Commands

### `stripe login`

Connect the CLI to your Stripe account by logging in to persist your secret key locally. The Stripe CLI runs commands using a global configuration or project-specific configurations. To configure the CLI globally, run:

```sh
stripe login
```

You'll be redirected to the Dashboard to confirm that you want to give the CLI access to your account. After confirming, a new API key will be created for the CLI.

> All configurations are stored in `~/.config/stripe/config.toml`, including login credentials. You can use the [`XDG_CONFIG_HOME`](https://wiki.archlinux.org/index.php/XDG_Base_Directory) environment variable to override this location. The configuration file is not automatically removed when the CLI is uninstalled.

**Command:** `stripe login`

#### Flags

*   `-i, --interactive` Use interactive configuration mode if you cannot open a browser and would like to manually provide an API key.
*   `--project-name=` You can create project-specific configurations with the `--project-name` flag, which can be used in any context. If you do not provide the `--project-name` flag for a command, it will default to the global configuration.

#### Examples

**Basic login**

```sh
stripe login
```

**Log in and specify a project**

```sh
stripe login --project-name=rocket-rides
```

```
Your pairing code is: excels-champ-wins-quaint
This pairing code verifies your authentication with Stripe.
Press Enter to open the browser ...
```

**Log in using interactive mode**

```sh
stripe login --interactive
```

```
Enter your API key:
Your API key is: sk_******************************p7dc
```

### `stripe logout`

Use the `logout` command to remove all credentials that connect the CLI to your Stripe account. By default, credentials will be removed for the default project. Alternatively, you can remove credentials for a specific project or all known projects listed in your configuration file.

> It will take about 24 hours from when you log out for your device's name to stop showing up on the account's dashboard.

**Command:** `stripe logout`

#### Flags

*   `-a, --all` Remove credentials for all projects listed in your configuration.
*   `--project-name=` Remove the credentials tied to a specific project in your configuration.

#### Examples

**Basic logout**

```sh
stripe logout
```

**Log out of a specific project**

```sh
stripe logout --project-name=rocket-rides
```

**Log out of all projects**

```sh
stripe logout --all
```

### `stripe config`

Use the `config` command to manually set configuration options for the CLI. The `config` command supports:

*   Setting options
*   Unsetting options
*   Listing all configured options
*   Opening the configuration file with your default editor

All commands support the `--project-name` global flag. You can define a unique configuration for individual projects.

**Command:** `stripe config`

#### Flags

*   `-e, --edit` Opens the configuration file in your default editor.
*   `--list` Lists all configured options (including defaults).
*   `--set ` Set a value for the specified configuration option.
*   `--unset ` Unset the configuration option and remove the key-value pair from the configuration file.

#### Examples

**Set a configuration option**

```sh
stripe config --set color on
```

**Unset a configuration option**

```sh
stripe config --unset color
```

**List the currently configured options**

```sh
stripe config --list
```

```
color = "on" [default]
device_name = "st-stripe1"
live_mode_api_key = "rk_live_abc123"
live_mode_publishable_key = "pk_live_abc123"
test_mode_api_key = "rk_test_abc123"
test_mode_publishable_key = "pk_test_abc123"
```

### `stripe completion`

The Stripe CLI supports autocompletion for macOS and Linux to make it easier to use the right commands with the CLI with the Bash and ZSH shells. Set up autocompletion by running `stripe completion`. Depending on your platform and shell, relevant instructions will be displayed. Details around setting up autocompletion can be also found in the [Terminal Autocompletion](https://docs.stripe.com/stripe-cli/configure.md#autocompletion) section of our configuration guide.

> Shell completion scripts are not currently supported on Windows.

**Command:** `stripe completion`

#### Flags

*   `--shell ` The shell for which autocompletion commands will be generated. By default the CLI will attempt to autodetect the platform.
    *   `bash` Use for Bash environments.
    *   `zsh` Use for ZSH environments.

#### Examples

**Basic usage**

```sh
stripe completion
```

**Specifying a shell**

```sh
stripe completion --shell zsh
```

### `stripe version`

Get the version of the Stripe CLI and check if software updates are available.

**Command:** `stripe version`

#### Examples

**Basic usage**

```sh
stripe version
```

```
stripe version 1.3.0
A newer version of the Stripe CLI is available.
```

### `stripe help`

Get help for any command in CLI with `stripe help [path to command]`.

> Every command will also accept the `-h` or `--help` flag to see help for that command.

**Command:** `stripe help`

#### Examples

**Basic usage**

```sh
stripe help login
```

```
Login to your Stripe account to setup the CLI
Usage:
  stripe login [flags]

Flags:
  -h, --help   help for login
...
```

### `stripe feedback`

Prints information about how to provide feedback for the Stripe CLI using [GitHub issues](https://github.com/stripe/stripe-cli/issues) and the [CLI feedback form](https://stri.pe/cli-feedback).

**Command:** `stripe feedback`

#### Examples

**Basic usage**

```sh
stripe feedback
```

```
We'd love to know what you think of the CLI:
* Report bugs or issues on GitHub: https://github.com/stripe/stripe-cli/issues
* Leave us feedback on features you would like to see: https://stri.pe/cli-feedback
```

## API Interaction Commands

### `stripe {resource command}`

Resource commands make API requests using the CLI for a given resource. The Stripe CLI has commands to interact with all types of Stripe API resources. A complete list of available resources and examples are included in the [API Reference Guide](https://docs.stripe.com/api.md). Select **Stripe CLI** from the language dropdown to see a complete example for each resource. Use the `help` command on any resource to see what operations you can perform. For example, run `stripe customers --help` to see help for the [Customers](https://docs.stripe.com/api/customers.md) resource. Use `stripe resources` to see a complete list of available resources.

> All commands support making live requests with the `--live` flag.

**Command:** `stripe {resource command}`

#### Arguments

*   `` Operation to perform on API object. Each type of API resource includes a set of operations that you can perform (such as `delete`, `list`, and `retrieve`).

#### Flags

*   `--param=value` Parameters to attach to the operation being performed.
*   `-d, --data ` Additional data to send with an API request. Supports setting nested values (e.g `nested[param]=value`).

#### Examples

**Listing supported operations**

```sh
stripe customers --help
```

```
Available Operations:
  create
  delete
  list
...
```

**Create a resource**

```sh
stripe customers create \
  --email=billing@example.com \
  --name="Jenny Rosen" \
  --description="My First Test Customer"
```

**Update a resource**

```sh
stripe customers update cus_9s6XKzkNRiz8i3 \
  -d "metadata[key]=value"
```

**Retrieve a resource**

```sh
stripe customers retrieve cus_9s6XKzkNRiz8i3
```

**Response**

```json
{
  "id": "cus_9s6XKzkNRiz8i3",
  "object": "customer",
  "address": null,
  "balance": 0,
  "created": 1680893993,
  "currency": null,
  "default_source": null,
  "delinquent": false,
  "description": "My First Test Customer",
  "discount": null,
  "email": "billing@example.com",
  "invoice_prefix": "0759376C",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null,
    "rendering_options": null
  },
  "livemode": false,
  "metadata": {},
  "name": "Jenny Rosen",
  "next_invoice_sequence": 1,
  "phone": null,
  "preferred_locales": [],
  "shipping": null,
  "tax_exempt": "none",
  "test_clock": null
}
```

### `stripe resources`

Resource commands make API requests using the CLI for a given resource. The Stripe CLI has commands to interact with all types of Stripe API resources. A complete list of available resources and examples are included in the [API Reference Guide](https://docs.stripe.com/api.md). Select **Stripe CLI** from the language dropdown to see a complete example for each resource. Use the `help` command on any resource to see what operations you can perform. For example, run `stripe customers --help` to see help for the [Customers](https://docs.stripe.com/api/customers.md) resource. Use `stripe resources` to see a complete list of available resources.

> All commands support making live requests with the `--live` flag.

**Command:** `stripe {resource command}`

#### Arguments

*   `` Operation to perform on API object. Each type of API resource includes a set of operations that you can perform (such as `delete`, `list`, and `retrieve`).

#### Flags

*   `--param=value` Parameters to attach to the operation being performed.
*   `-d, --data ` Additional data to send with an API request. Supports setting nested values (e.g `nested[param]=value`).

#### Examples

**Listing supported operations**

```sh
stripe customers --help
```

```
Available Operations:
  create
  delete
  list
...
```

**Create a resource**

```sh
stripe customers create \
  --email=billing@example.com \
  --name="Jenny Rosen" \
  --description="My First Test Customer"
```

**Update a resource**

```sh
stripe customers update cus_9s6XKzkNRiz8i3 \
  -d "metadata[key]=value"
```

**Retrieve a resource**

```sh
stripe customers retrieve cus_9s6XKzkNRiz8i3
```

**Response**

```json
{
  "id": "cus_9s6XKzkNRiz8i3",
  "object": "customer",
  "address": null,
  "balance": 0,
  "created": 1680893993,
  "currency": null,
  "default_source": null,
  "delinquent": false,
  "description": "My First Test Customer",
  "discount": null,
  "email": "billing@example.com",
  "invoice_prefix": "0759376C",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null,
    "rendering_options": null
  },
  "livemode": false,
  "metadata": {},
  "name": "Jenny Rosen",
  "next_invoice_sequence": 1,
  "phone": null,
  "preferred_locales": [],
  "shipping": null,
  "tax_exempt": "none",
  "test_clock": null
}
```

### `stripe fixtures`

Use a JSON file to issue a series of API requests. This can be useful when generating sample data, executing specific flows, or testing API behavior. The structure of the JSON file outlines the set of requests to perform, known as _fixture requests_. When you specify a request's `name`, the CLI stores the response so you can reference the output in subsequent requests. The `path` property specifies the Stripe URL route for the API resource used in the request (e.g. `/v1/customers`). For example, to reference the response for the request named `json_path`:

*   Accessing attributes in responses: `${name:json_path}`
*   Accessing environment variables: `${.env:VARIABLE_NAME|}`

Fixture queries must start with `${` and end with `}` and can be included in fixture requests. `name` is the name of the request assigned as part of the fixture (`fixtures[].name`) and `json_path` is a dot-path to the specific variable requested. For example:

*   Use `${cus_jenny_rosen:id}` to access a top-level attribute.
*   Use `${cus_jenny_rosen:billing_details.address.country}` to access nested data.
*   Use `{cus_jenny_rosen:subscriptions.data.#.id}` to access data within a list at index #.
*   Use `${.env:PHONE}` to access environment variables (supports `.env` files). Environment variables can specify default values with the pipe character (`|`). For example:
    *   `${.env:EMAIL|jane@stripe.com}`
    *   `${.env:CUSTOMER|cus_1234}`

**Command:** `stripe fixtures`

#### Arguments

*   `` Use the JSON file at the given path that includes fixture requests to run.

#### Fields

*   `_meta` Metadata used by CLI during execution.
*   `template_version` Version of the template that is running (enables us to support potentially backwards-incompatible changes).
*   `fixtures` List of requests to execute.
*   `name` Name of the request, used to later reference the response
*   `expected_error_type` Indicates that this request is expected to return an error of the specified [error type](https://docs.stripe.com/error-codes). When set, the fixture continues executing subsequent requests even if this request returns an error

## Stripe Samples

### `stripe samples create`

Create a local copy of a sample, choosing which integration pattern and programming language to use for the client and server. The configuration is automatically bootstrapped when possible.

**Command:** `stripe samples create`

#### Arguments

*   `` Name of the sample used to create a local copy.
*   `` Destination path for the created sample.

#### Flags

*   `--force-refresh` Force a refresh of the cached list of Stripe Samples.

#### Examples

**Create a local copy of a sample**

```sh
stripe samples create accept-a-payment
```

**Specify a destination path**

```sh
stripe samples create accept-a-payment ./accept-a-payment-sample
```

### `stripe samples list`

A list of available [Stripe Samples](https://stripe.dev/samples) that can be created and bootstrapped by the CLI.

> See the complete list of [Stripe Samples](https://stripe.dev/samples).

**Command:** `stripe samples list`

#### Examples

**List available Stripe Samples**

```sh
stripe samples list
```

```
A list of available Stripe Samples:
accept-a-payment Learn how to accept a payment
  Repo: https://github.com/stripe-samples/accept-a-payment
card-brand-choice Supporting Card Brand Choice with Stripe.
  Repo: https://github.com/stripe-samples/card-brand-choice
charging-a-saved-card Learn how to charge a saved card
  Repo: https://github.com/stripe-samples/charging-a-saved-card
...
```

### `stripe serve`

Start an HTTP server to serve static files. By default, the current working directory will be used. This command works well alongside [Stripe Samples](https://stripe.dev/samples), so you can easily serve files from any local copy of a Sample.

**Command:** `stripe serve`

#### Arguments

*   `` Path of the directory to serve files from.

#### Flags

*   `--port ` Port the HTTP server should use.

#### Examples

**Basic Usage**

```sh
stripe serve ./sales-tax-sample
```

```
Starting
```

## Additional Commands

### `stripe terminal quickstart`

Use the `terminal quickstart` command to get up and running fast with Stripe Terminal and the Verifone P400 reader.

**Command:** `stripe terminal quickstart`

#### Flags

*   `--api-key=` This CLI command only supports using the --api-key flag.

#### Examples

**Terminal quickstart**

```sh
stripe terminal quickstart
```

## Global Flags

The Stripe CLI supports a number of flags for every command.

**Command:** `stripe {command} `

#### Flags

*   `--api-key ` Use the Stripe account associated with this Stripe API secret key.
*   `--color ` Enable or disable color output.
    *   `on` Enable color output.
    *   `off` Disable color output.
    *   `auto` Use the default output color based on global settings.
*   `--config ` Use this file path for the CLI's configuration file (default: `$HOME/.config/stripe/config.toml`).
*   `--device-name ` Run this command on behalf of another device.
*   `-h, --help` Provides the help documentation for a given command, including the supported flags and arguments.
*   `--log-level ` Set the level of detail for log messages (default: `info`)
    *   `debug` Useful for development purposes.
    *   `info` Shows standard logs that come up.
    *   `warn` Shows warnings that are detected.
    *   `error` Shows every log including errors that arise.
*   `-p, --project-name ` Define a project name for the CLI's current configuration. Using the `--project-name` flag enables multiple configurations across Stripe accounts (stored within one configuration file), and any command can run in the context of a project (default: `"default"`).
*   `-v, --version` Prints the version of the Stripe CLI. This flag is meant to run without any other flags or arguments set.

## Further Information

### Using with Docker

A [Docker image](https://hub.docker.com/r/stripe/stripe-cli) allows you to run the Stripe CLI in a container. You can set two environment variables that the CLI will use:

*   `STRIPE_API_KEY`: the API key to use for the CLI.
*   `STRIPE_DEVICE_NAME`: the device name for the CLI, visible in the Dashboard.

Since Docker containers are ephemeral, `stripe-cli login` cannot be used without defining a data volume. You can use the `--api-key` flag instead.

#### Example

```title
Running in a docker container
```

### Telemetry

The Stripe CLI includes a telemetry feature that collects usage data to help us improve the developer experience. This feature is **enabled by default**.

#### What data is collected

The Stripe CLI collects:

*   Command usage patterns (which commands are run, how often)
*   Error rates and types to help identify issues
*   Performance metrics (command execution times)
*   Operating system and CLI version information
*   If detected, the name of AI coding agents invoking the CLI (such as Claude Code, Cursor, or Cline)

#### What is NOT collected

We do **not** collect:

*   API keys or authentication credentials
*   Personal information or identifiable data
*   File names, paths, or source code
*   Command arguments or flag values
*   Any data from your Stripe account

#### Why we collect this data

Telemetry data helps us:

*   Prioritize which features and commands to improve
*   Identify and fix bugs more quickly
*   Understand how developers use the CLI in different environments
*   Optimize performance for common workflows

#### How to opt out

To disable telemetry, set the `STRIPE_CLI_TELEMETRY_OPTOUT` environment variable to `1` or `true`:

```bash
# Opt out for a single session
STRIPE_CLI_TELEMETRY_OPTOUT=1 stripe [command]

# Opt out permanently (add to your shell profile)
export STRIPE_CLI_TELEMETRY_OPTOUT=1
```

After opting out, the CLI will not send any telemetry data.

## License

The [Stripe CLI](https://github.com/stripe/stripe-cli) is licensed under the [Apache License 2.0](https://github.com/stripe/stripe-cli/blob/master/LICENSE) and verified on GitHub as being owned by [Stripe](https://github.com/stripe).