The Stripe CLI is a command-line interface for Stripe that can:
loginto your Stripe account and authenticate the CLI
listenfor webhooks and forward them to a local server
- Run resource commands for things like
stripe charges create
deletecommands to the Stripe API
triggera limited set of webhook events
- Tail your test mode API request logs
- Pull Stripe status from status.stripe.com
The main focus for this initial release is to improve the developer experience while integrating and testing webhooks. Interactions through the CLI are currently limited to test mode only.
Table of Contents
- Stripe CLI
$ brew install stripe/stripe-cli/stripe
- Add Bintray's GPG key to the apt sources keyring:
$ sudo apt-key adv --keyserver hkp://pool.sks-keyservers.net:80 --recv-keys 379CE192D401AB61
- 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
- Update the package list:
$ sudo apt-get update
- Install the CLI:
$ sudo apt-get install stripe
- 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/
- Update the package list:
$ sudo yum update
- Install the CLI:
$ sudo yum install stripe
$ scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git
$ scoop install stripe
The CLI is also available as a Docker image:
$ docker run --rm -it stripe/stripe-cli version stripe version x.y.z (beta)
Without package managers
Instructions are also available for installing and using the CLI without a package manager.
The Stripe CLI runs commands using a global configuration or project-specific configuration. To configure the CLI globally, run:
$ stripe login
You'll be redirected to the Stripe dashboard to confirm that you want to give access to your account to the CLI. After confirming, a new API key will be created and returned to the CLI.
You can create project-specific configurations with the
--project-name flag, which can be used in any context. To create an initial configuration:
$ stripe login --project-name=rocket-rides
If you do not provide the
--project-name flag for a command, it will default to the global configuration.
All configurations are stored in
~/.config/stripe/config.toml but you can use the
XDG_CONFIG_HOME environment variable to override this location.
You can also provide an API key manually by passing the
$ stripe login --interactive Enter your API key: sk_test_foobar Your API key is: sk_test_**obar How would you like to identify this device in the Stripe Dashboard? [default: st-tomer1] You're configured and all set to get started
listen command establishes a direct connection with Stripe, delivering webhook events to your computer directly. Stripe will forward all webhooks tied to the Stripe account for the a given API key.
Note: You do not need to configure any webhook endpoints in your Dashboard to receive webhooks with the CLI.
listen accepts all webhook events displays them in your terminal. To forward events to your local app, use the
--forward-to flag with the location:
--forward-to will return a webhook signing secret, which you can add to your application's configuration:
$ stripe listen --forward-to https://example.com/hooks > Ready! Your webhook signing secret is whsec_oZ8nus9PHnoltEtWZ3pGITZdeHWHoqnL (^C to quit)
The webhook signing secret provided will not change between restarts to the
You can specify which events you want to listen to using
--events with a comma-separated list of Stripe events.
$ stripe listen --events=payment_intent.created,payment_intent.succeeded
You may have webhook endpoints you've already configured with specific Stripe events in your Dashboard. The Stripe CLI can automatically listen to those events with the
--load-from-webhooks-api flag, used alongside the
--forward-to flag. This will read any endpoints configured in test mode for your account and forward associated events to the provided URL:
$ stripe listen --load-from-webhooks-api --forward-to https://example.com/hooks
Note: You will receive events for all interactions on your Stripe account. There is currently no way to limit events to only those that a specific user created.
Should you need to also listen to connect events for all connected accounts, you can use the separate
$ stripe listen --forward-to localhost:3000/webhook --forward-connect-to localhost:3000/connect_webhook
You can easily make API requests using the CLI:
$ stripe charges retrieve ch_123 $ stripe charges create --amount=100 --currency=usd --source=tok_visa $ stripe charges update ch_123 -d "metadata[key]=value"
For a full list of available resources, type
stripe resources or the wiki page.
The CLI has three commands that let you interact with the Stripe API in test mode. You can easily make
DELETE commands with the Stripe CLI.
For example, you can retrieve a specific charge:
$ stripe get /charges/ch_123
You can also pass data in using the
$ stripe post /charges -d amount=100 -d source=tok_visa -d currency=usd
These commands support many of the features on the Stripe API (e.g. selecting a version, pagination, and expansion) through command-line flags, so you won't need to provide specific headers. For a full list of supported flags, see the wiki page.
You can pipe the output of these commands to other tools. For example, you could use jq to extract information from JSON the API returns, and then use that information to trigger other API requests.
Here’s a simple example that lists
past_due subscriptions, extracts the IDs, and cancels those subscriptions:
$ stripe get /subscriptions -d status=past_due | jq ".data.id" | xargs -I % -p stripe delete /subscriptions/%
The CLI will allow you to trigger a few test webhook events to conduct local testing. These test webhook events are real objects on the API and may trigger other webhook events as part of the test (e.g. triggering
payment_intent.succeeded will also trigger
The webhook events we currently support are listed in the CLI help or on the wiki page.
To trigger an event, run:
$ stripe trigger <event>
logs tail establishes a direct connection with Stripe and enables you to tail your test mode Stripe API request logs in real-time from your terminal.
logs tail will display all of your test mode request logs. To begin log tailing, run:
$ stripe logs tail
A number of built-in filtering options are also supported:
--filter-account, (Connect only) supports
connect_in(incoming Connect requests),
connect_out(outgoing Connect requests), and
--filter-ip-address, supports a direct match with any ip address
--filter-request-path, supports a direct match to any Stripe path (e.g.,
--filter-status-code, supports any status code that is a
Multiple filters can be used together, where a log must match all filters to be shown:
$ stripe logs tail --filter-http-method POST --filter-status-code-type 4XX
Multiple values for a single filter can also be specified as a comma-separated list, where a log only needs to match one of the values:
$ stripe logs tail --filter-http-method GET,POST
With Stripe Samples, you can experience fully-functional sample Stripe integrations covering different integration styles, languages, and frameworks. The CLI supports downloading and configuring specific samples locally, letting you quickly get up-and-running with a sample.
To see a list of samples supported by your version of the CLI, run:
$ stripe samples list
To create a new sample locally, select one of the samples from the list and run:
$ stripe samples create <name>
The CLI will configure the sample with the API key used after logging in as well the webhook signing secret from running the
You can load Stripe status from the CLI instead of going to status.stripe.com. The CLI status loads from the status site, which is the canonical source of truth.
To load status, run:
$ stripe status ✔ All services are online. As of: July 23, 2019 @ 07:52PM +00:00
The status command supports several different flags:
--verboselists out individual Stripe system status using.
--format jsonhas the CLI render the status as a JSON blob for easier grepping and for using with tools like
--pollwill continuously check the status site for changes
--poll-ratelet's you specify how often to check the status site. The default is once every 60 seconds and this can be modified down to once every 5 seconds.
--hide-spinnerwill hide the spinner that's shown when polling.
If you need, you can manually set configuration values for the CLI using the
config command. The config command supports:
- Setting values
- Unsetting values
- Listing config values
- Opening the editor to the config file
All operations support the
--project-name global flag to manipulate specific projects.
To set values, run
stripe config with the key name and the value.
$ stripe config <name> <value>
To unset a value, pass the
--unset flag with the name:
$ stripe config --unset <name>
To list all config values, run with
$ stripe config --list
To open your editor at the config file, using
$ stripe config -e
open command is a shortcut available for users to quickly open up different parts of the Stripe docs website and dashboard. To run it, invoke:
$ stripe open <shortcut>
All of the available shortcuts are listed in the wiki page.
For dashboard pages, you can also add the
--livemode flag to open the page directly in live mode.
Developing the Stripe CLI
If you're working on developing the CLI, it's recommended that you alias the go command to run the dev version. Place this in your shell rc file (such as
The Stripe CLI is built using Go. To download and compile the source code, run:
$ go get -u github.com/stripe/stripe-cli/...
cd into the directory and setup the dependencies:
$ cd go/src/github.com/stripe/stripe-cli $ make setup
Once setup, run the test suite to make sure everything works as expected:
$ make test
You can invoke the local version of the CLI by running:
$ go run cmd/stripe/main.go
Optionally, you can add this to your shell profile to make running the local version a little easier.
alias stripe-dev='go run cmd/stripe/main.go'
To run the linter, run
golangci-lint is installed:
brew install golangci/tap/golangci-lint
You can run tests with:
$ make test
To release a new version, checkout
master and then run
make release. It'll prompt you for a version and will then push a new tag.