# Stripe CLI Documentation

This documentation covers the Stripe Command Line Interface (CLI), a powerful tool for developers to build, test, and manage their Stripe integrations directly from the terminal.

## Core Functionality

The Stripe CLI offers a wide range of commands to interact with your Stripe account and integration. Key functionalities include:

*   **Managing API Objects:** Create, retrieve, update, and delete various Stripe API resources.
*   **Real-time Log Tailing:** Monitor API request logs as they happen.
*   **Webhook Testing:** Securely test webhooks without relying on third-party tunneling services.
*   **Sample Integration Management:** Download, build, and serve Stripe Samples.

## Getting Started

### Installation

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

### Authentication

To connect the CLI to your Stripe account, you need to log in.

*   **`stripe login`**: This command initiates the login process, redirecting you to the Stripe Dashboard to authorize the CLI. A new API key will be created for your CLI.
    *   **Interactive Login (`--interactive`)**: Use this flag if you cannot open a browser and need to manually provide an API key.
    *   **Project-Specific Configurations (`--project-name`)**: Create separate configurations for different projects. If not specified, the global configuration is used.
*   **`stripe logout`**: Removes credentials that connect the CLI to your Stripe account. You can log out of specific projects or all projects.

### Configuration

The Stripe CLI uses configuration files to store settings and credentials.

*   **Configuration File Location**: Configurations are stored in `~/.config/stripe/config.toml`. This location can be overridden using the `XDG_CONFIG_HOME` environment variable.
*   **`stripe config`**: This command allows you to manually manage CLI configuration options.
    *   `--set`: Set a configuration option.
    *   `--unset`: Unset a configuration option.
    *   `--list`: List all configured options.
    *   `--edit`: Open the configuration file in your default editor.
*   **API Keys**: The CLI supports several ways to use API keys:
    *   `stripe login` (recommended for ease of use)
    *   `stripe config`
    *   `--api-key` flag (for one-off commands)
    *   Environment variables (`STRIPE_API_KEY`, `STRIPE_DEVICE_NAME`)

## Key Commands and Features

### Resource Management

*   **`stripe resources`**: Lists all available API resources you can interact with.
*   **Resource Commands**: Directly manage API resources (e.g., `stripe customers create`, `stripe charges retrieve`). These commands accept arguments for operations and flags for parameters and data.
    *   `--live`: Make live requests instead of test requests.
    *   `--param=value`: Specify parameters for the operation.
    *   `-d, --data`: Provide additional data for the API request.
*   **`stripe fixtures`**: Use a JSON file to issue a series of API requests, useful for generating sample data and testing API behavior. You can reference responses from previous requests within the same fixture file.

### Samples and Development

*   **`stripe samples list`**: Displays a list of available Stripe Samples that can be created and bootstrapped by the CLI.
*   **`stripe samples create <name> [destination_path]`**: Creates a local copy of a specified Stripe Sample.
    *   `--force-refresh`: Forces a refresh of the cached list of Stripe Samples.
*   **`stripe serve [path]`**: Starts an HTTP server to serve static files, useful for local development with Stripe Samples.
    *   `--port`: Specify the port for the HTTP server.

### Utility Commands

*   **`stripe completion`**: Sets up shell autocompletion for Bash and Zsh to make using the CLI easier.
    *   `--shell`: Specify the shell for which autocompletion commands will be generated.
*   **`stripe feedback`**: Provides information on how to give feedback for the Stripe CLI.
*   **`stripe help [command]`**: Displays help documentation for any command. The `-h` or `--help` flag can be used with any command.
*   **`stripe version`**: Shows the current version of the Stripe CLI and checks for updates.
*   **`stripe terminal quickstart`**: Guides you through setting up Stripe Terminal with a Verifone P400 reader.

### Global Flags

These flags can be used with most Stripe CLI commands:

*   `--api-key`: Use a specific Stripe API secret key.
*   `--color`: Enable or disable color output (`on`, `off`, `auto`).
*   `--config`: Specify a custom path for the CLI's configuration file.
*   `--device-name`: Run a command on behalf of another device.
*   `-h, --help`: Show help documentation for a command.
*   `--log-level`: Set the level of detail for log messages (`debug`, `info`, `warn`, `error`).
*   `-p, --project-name`: Define a project name for the current configuration.
*   `-v, --version`: Print the version of the Stripe CLI.

### Advanced Information

*   **Docker Integration**: The Stripe CLI can be run within a Docker container. Environment variables `STRIPE_API_KEY` and `STRIPE_DEVICE_NAME` can be used. Note that `stripe-cli login` is not recommended in ephemeral containers; use the `--api-key` flag instead.
*   **Telemetry**: The Stripe CLI collects usage data to improve the developer experience. This feature is enabled by default but can be opted out by setting the `STRIPE_CLI_TELEMETRY_OPTOUT` environment variable. Data collected includes command usage, error rates, performance metrics, and version information. Sensitive data like API keys and personal information are NOT collected.
*   **License**: The Stripe CLI is licensed under the Apache License 2.0.