Using the Stripe CLI

    Learn how to use the Stripe CLI to simplify your development workflow.

    The Stripe CLI helps you build, test, and manage your Stripe integration right from the terminal.

    With the CLI, you can:

    • Securely test webhooks without relying on third-party tunneling software.
    • Trigger webhook events to easily test your integration.
    • Tail API request logs in real time.
    • Create, retrieve, update, and delete API objects.
    • Follow the steps below to get started with the Stripe CLI:

    Step 1: Install the Stripe CLI

    To install the Stripe CLI with homebrew, run:

    brew install stripe/stripe-cli/stripe

    To install the Stripe CLI on Debian and Ubuntu-based distributions:

    1. Add Bintray’s GPG key to the apt sources keyring:
    sudo apt-key adv --keyserver hkp://pool.sks-keyservers.net:80 --recv-keys 379CE192D401AB61
    1. Add stripe-cli’s apt repository to the apt sources list:
    echo "deb https://dl.bintray.com/stripe/stripe-cli-deb stable main" | sudo tee -a /etc/apt/sources.list
    1. Update the package list:
    sudo apt-get update
    1. Install the CLI:
    sudo apt-get install stripe

    Install the Stripe CLI on RedHat and CentOS-based distributions:

    1. Add stripe-cli’s yum repository to the yum sources list:
    wget https://bintray.com/stripe/stripe-cli-rpm/rpm -O bintray-stripe-stripe-cli-rpm.repo && sudo mv bintray-stripe-stripe-cli-rpm.repo /etc/yum.repos.d/
    1. Update the package list:
    sudo yum update
    1. Install the CLI:
    sudo yum install stripe

    To install the Stripe CLI with Scoop, run:

    scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git
    scoop install stripe

    To install the Stripe CLI without homebrew:

    1. Download the latest mac-os tar.gz file from https://github.com/stripe/stripe-cli/releases/latest
    2. Unzip the file: tar -xvf stripe_X.X.X_mac-os_x86_64.tar.gz

    Optionally, install the binary in a location where you can execute it globally (e.g., ~/usr/local/bin).

    To install the Stripe CLI without a package manager:

    1. Download the latest linux tar.gz file from https://github.com/stripe/stripe-cli/releases/latest
    2. Unzip the file: tar -xvf stripe_X.X.X_linux_x86_64.tar.gz
    3. Run the executable: ./stripe

    To install the Stripe CLI without Scoop, run:

    1. Download the latest windows tar.gz file from https://github.com/stripe/stripe-cli/releases/latest
    2. Unzip the stripe_X.X.X_windows_x86_64.tar.gz file
    3. Run the unzipped .exe file

    The Stripe CLI is also available as a Docker image. Run the following command to install the latest version:

    docker run --rm -it stripe/stripe-cli latest

    Once you have the Stripe CLI installed, run stripe login in the command line to generate a pairing code to link to your Stripe account. Press Enter to launch your browser and log in to your Stripe account to allow access.

    stripe login
    Your pairing code is: humour-nifty-finer-magic
    Press Enter to open up the browser (^C to quit)
    

    The generated API key is valid for 90 days. You can modify or delete the key under API Keys in the Dashboard.

    If you want to use an existing API key, use the --api-key flag:

    stripe login --api-key `{{TEST_API_KEY}}`
    Your pairing code is: humour-nifty-finer-magic
    Press Enter to open up the browser (^C to quit)
    

    Step 3: Listen for events

    To confirm you can view webhook events from your Stripe account, run stripe listen:

    stripe listen
    Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
    

    Events are only created once specific actions are taken, so you might not see any events until you create a new object. In a new command prompt, trigger a payment_intent.created event:

    stripe trigger payment_intent.created
    

    You should see some information about the event in the command prompt where you ran the stripe listen command:

    stripe listen
    Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
    INFO Received event: '{{WEBHOOK_EVENT_ID}}' [type: payment_intent.created]
    

    Step 4: Forward events to your server

    You can also use the Stripe CLI to forward events to your server with the --forward-to flag:

    stripe listen --forward-to localhost:5000/hooks
    Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
    

    As in the previous step, events from your account show up in the command prompt output along with the response from your server:

    stripe listen --forward-to localhost:5000/hooks
    Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
    INFO Received event: '{{WEBHOOK_EVENT_ID}}' [type: payment_intent.created]
    INFO Got response from local endpoint, status=200
    

    Note that responses from your server are not returned to Stripe and won’t show up in the Dashboard.

    API requests

    You can make API requests directly through the Stripe CLI. Run stripe resources to see the complete list of resources available and use --help or review the API Reference to get more information for each resource.

    stripe payment_intents create --amount=100 --currency=usd
    

    If you want to make requests for a specific API version, use the --stripe-version flag. See the changelog for the complete list of API versions.

    stripe payment_intents create --amount=100 --currency=usd --stripe-version 2019-03-14
    

    API versions

    If you’re on an older version of the Stripe API, you can still test how webhook events behave on the latest API version without upgrading. To test webhook events on the latest API version, run the listen command with the --latest flag. Using this flag does not upgrade your account’s API version you can run it safely without any side effects.

    stripe listen --forward-to localhost:5000/hooks --latest
    Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
    

    Supported events

    Events triggered through the CLI are real objects in the Stripe API that you can interact with. These events can also trigger other webhook events (e.g., a payment_intent.succeeded event will also trigger a payment_intent.created event).

    To see a list of supported events, visit the wiki. If you’d like to see support for an event that isn’t listed above, let us know.

    More information

    To see what else you can do with the Stripe CLI, use the stripe help command or check out the project on GitHub.

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page