Introduction to the Stripe CLI

The Stripe CLI (command line interface) and Stripe for VS Code extension are essential tools when you’re building, testing and managing your Stripe integration. In this article you’ll learn about the powerful features of the Stripe CLI and how you can leverage those features both on the command line and via the VS Code extension.

Prerequisites

If you’d like to follow along you can install the Stripe CLI on many different platforms. The instructions to install it for your system are here, and you can install the VS Code extension via the VS Code marketplace. You can also follow along with most of this tutorial using the Stripe Shell, which is the Stripe CLI available right in the browser.

Connecting to your Stripe account

In order to connect to your Stripe account, we need to login using the CLI:

stripe login

We’ll be issued a pairing code and prompted to hit enter to open a browser to confirm the pairing code with our account:

When we have verified the pairing code we can allow access. It’s possible to connect the CLI to any of the accounts that would be listed here but in my case I only have one account named VS Code.

Then we can close the browser and return to the CLI and we’ll see that we’re connected.

The basics: CRUD

CRUD stands for create, read, update, and delete. We’ll see how we can use these actions to manage resources in the Stripe API. By issuing the command stripe resources we see an extensive list of the API resources that we can interact with.

We’ll focus on one resource for the moment, a common resource that we’ll need when integrating with Stripe, the Customer object. Let’s create a customer:

stripe customers create --name 'Matt Ling'

The --name parameter maps to the top level name of the Customer object.

We can retrieve that resource now from the API with its ID which we’ll copy from the previous create output:

stripe customers retrieve cus_MDFfFTRXkhvNqP

Next let's update that customer using its ID:

stripe customers update cus_MDFfFTRXkhvNqP --name 'Martina Ling'

We can see that the customer’s name has been updated. Finally we’ll delete that customer:

stripe customers delete cus_MDFfFTRXkhvNqP -c. Here we’re passing the shorthand -c flag to tell the CLI not to ask for confirmation of the deletion:

While this may seem quite rudimentary, it’s an illustration of how powerful the CLI is as a tool for learning and exploration. Let’s take a look at a much more involved use case and see how the CLI can quickly and easily enable us to realize that case. In the last four commands we did simple things like create, read, update, and delete.

But some Stripe API endpoints are for taking actions like transitioning objects from one state to another, like Payment Intents being created and then transitioning to requiring action (for authentication) or succeeding. Let’s create a more complex call using the Payment Intents API. I’d like to create a payment for a customer, confirm it immediately, using a pre-tokenized credit card, and at the same time save that payment method against that customer for off-session usage in the future. Charging a user off-session means that you can attempt to charge that customer's payment method while they are not present on your site or app. With the CLI we can quickly create this use case without wrangling many objects in the dashboard or writing a single line of code:

stripe payment_intents create --customer cus_MDFjyVfH75GQ49 --amount 1111 --currency eur --confirm true --payment-method pm_card_visa --setup-future-usage off_session

One remark on the params we’re passing here. While the API argument uses underscores, the CLI expects “kebab cased” arguments i.e. -–payment-method. We can also pass structured data to the API using -d and the url encoded form of the argument name. This is very similar to cURL.

Let’s jump into the dashboard to inspect everything we’ve achieved here:

We can see that the payment was made, the customer was associated with the payment, and that the payment method was set up for future off-session payments.

Logging

While you’re developing your Stripe integration, it’s immensely useful to see how your system is interacting with the Stripe API. With the Stripe CLI you can stream your API logs in test mode — in real time on the command line — giving you immediate insight into how your integration is working. Let’s tail the logs and issue a few CLI commands and see the output.

stripe logs tail

stripe customers list

We can see in real time that the API received an HTTP GET request to the v1 customers endpoint and it responded with an HTTP 200 OK. Let’s issue the create Customer command that we used earlier:

stripe customers create --name 'Matt Ling'

Now we can see an HTTP POST request to create that customer. This is incredibly useful when you’re developing your system. Imagine you have a sophisticated multistep checkout process on your site. While tailing the logs using the CLI, you can see in real time at every step of the way that your integration is making all of the appropriate calls at the right time.

Webhook events

When interacting with Stripe either via the dashboard or via the API, a side effect of those interactions is that events will be generated about important moments. Those events could include things such as customers being created, or payments being made. There’s a myriad of events about which you can be notified, which you can see listed here. These events are also known as webhooks or webhook events.

Listening for, and reacting to those webhook events is a highly recommended, even essential part of your Stripe integration. The part of your system that should listen for those events, is called a webhook endpoint. Let’s recap what that is at a high level. Just as your system can make HTTP calls to Stripe to carry out actions like creating payments, Stripe can also make HTTP calls to your system to inform you of important events. Therefore, Stripe needs to know about an HTTP route into your system to which we can POST webhook events.

Ultimately, the goal of listening for and reacting to events is to execute your business functions like creating and tracking customers in your own database, sending out orders, or provisioning access to services.

Firstly, let’s establish a real time connection to our account to see what events are being generated:

stripe listen

Now let’s execute a command that will generate an event. We’ll create another customer:

stripe customers create --name 'Matt Ling'

We can see that a customer.created event was emitted and it was streamed in real time by the CLI.

In a production, test or QA environment, your webhook events will be sent to your servers for processing. But while you're developing a webhook endpoint on your local machine, you’d be right to wonder how you can grab the events you’re seeing in the stripe listen output and tunnel them into your local dev server.

The answer here is that the listen command supports listening for and forwarding events to an endpoint of your choosing. Let’s presume that you have a test server running on localhost:4242 with a route into your app called /webhook-endpoint. In my case I have a simple node server with a webhook endpoint running on my local machine that does nothing more than echo the type of event that it receives out to the console.

Now let’s listen for events on our account and forward them to this endpoint:

stripe listen --forward-to localhost:4242/webhook-endpoint

As mentioned earlier, there’s many ways to generate events on your account. You can interact with the dashboard, write code to hit the API, or execute commands on the CLI. We’ve seen commands earlier that will create events like creating customers, but sometimes you might want to cut to the chase and receive an event that may require quite a number of API interactions to complete.

A great example of this is the checkout.session.completed event. In order for that event to be fired under normal circumstances, a session must be created, the user redirected there, they fill out their payment details and complete the checkout session. But in testing, if we just want to receive that event in our webhook endpoint, we can simply “trigger” that event using the CLI.

stripe trigger checkout.session.completed

Looking at the output of the CLI we can surmise what the CLI is doing, it’s creating fixtures for each API call that would be required to generate a checkout session completed event as is doing the heavy lifting for you. We can also see the events streaming in via the CLI, and in the third pane, the events being echoed out by our simple web server running on localhost:

If your system uses code hot loading, this is a very quick and fun way to develop a webhook endpoint, make a code change, trigger an event, test and observe the results. Let’s take a look at how all of this is supported inside the VS Code development environment.

Stripe for VS Code extension

The Stripe for VSCode extension supports all of the functionality of the Stripe CLI embedded right into the IDE and even more helpful features, let’s cover those first.

Securing your API keys

Keeping your secret keys secure is an essential security measure to make sure that no bad actor can ever acquire those keys and perform API calls against your account. The VS Code extension will detect if a secret key has inadvertently been included in the source code and will flag this as an error.

Stripe code snippets

The VS Code extension also provides helpful snippet completion that helps to speed up development. For example, let’s start typing stripe.checkout and we’ll be presented with all of the snippet options that will help us to perform calls against the checkout API. Furthermore, once you have chosen a snippet, you can hover over the different parts of the method chain and be redirected directly into the accompanying documentation.

Tailing logs in VS Code

Just as we could do on the command line, we can tail the logs in VS Code without leaving the IDE. If I click on Start streaming API logs and trigger a customer created event, we’ll see the API call for that creation call being streamed in real time:

Streaming events

Just as we saw on the command line we can stream real time events in the IDE too. If we click on Start streaming events and then trigger a checkout.session.created event we’ll also see the events being listed here:

Forwarding events to a local server

If we select Forward events to your local machine:

we’ll be prompted to provide a URL to which we would like to forward events to. A connect webhook endpoint will also be queried but we can use the same endpoint for now as connect is out of scope for this demo.

We’ll also make sure that the same echo webhook endpoint is running on localhost:

If we trigger the checkout.session.completed event using the Trigger new default event option:

We’ll see the events streaming in via the listen command and being forwarded on to our server:

The Stripe CLI underpinning the VS Code extension is an immensely productive way to learn and experiment with the API, tail your logs, build and test a webhook endpoint and all of that fully integrated with VS Code.

Summary

The Stripe CLI is an essential set of tools for your toolchain when building your Stripe integration. We’re excited to hear what you’re building with it whether it’s accepting payments, using Terminal, or building a subscription service. Let us know what you’re working on!

About the author

Matthew Ling (@mattling_dev) is a Developer Advocate at Stripe. Matt loves to tinker with new technology, adores Ruby and coffee and also moonlighted as a pro music photographer. His photo site is at matthewling.com and developer site is at mattling.dev.

Stay connected

In addition, you can stay up to date with Stripe in a few ways:

📣 Follow us on Twitter
💬 Join the official Discord server
📺 Subscribe to our Youtube channel
📧 Sign up for the Dev Digest