Introduction to the Stripe CLI

[Music] as you begin the journey of implementing a stripe integration we want to arm you with a really powerful tool that will help you build test and manage your integration so enter the star of today's show the stripe CLI or the stripe command-line interface it's a command-line utility for securely testing your web hooks tailing your API request logs creating updating and retrieving API objects and much more that really just speeds up the common tasks and workflows so the content in today's episode acts as a foundational reference point to other developer office hours episodes and so whether you're just getting started or a seasoned stripe integrator this is going to be a great place to jump in welcome back to stripe developer office hours I'm CJ developer support engineer here at stripe and the stripe CLI has become an invaluable part of my workflow I'm really excited to share it with you so let's take a quick look at the agenda for today so to begin we'll install and connect the stripe CLI to our account and then we'll look at some of the API resource commands and pair those with another command line tool called JQ and next we'll explore the web hook commands that allow us to listen for web hook events and also trigger those event notifications and then we'll wrap with just a lightning round of the quick winds and other utilities that are currently available as part of the stripe CLI so the first thing I wanted to do is jump over to the wiki page for the stripes Eli's github and show you this this installation Docs this is where we're really going to start start going here or get going so for Mac you can use a homebrew to install for Linux you know for various distributions we have some installation instructions here and we also have a couple of ways you can install with Windows or as a docker image so since I'm on a Mac I'm gonna use this brew install command and I'm using I term today but really you can use any terminal that doesn't matter if you're on a Mac and you're really just sort of getting started you can use command space to open up the spotlight or Alfred finders and then type terminal or type I term to open up this window okay so I'm just gonna paste in the brew install command and this is going to install the stripe see alive this is going to be our command-line utility and as soon as the stripe CLI is installed there are some things that we can do so the very first thing I want to do is just try to type stripe and that'll show me all the commands that I'm that are available to run and kind of the way that we use the stripe command so the way that the way this works is we type stripe and then a space and then our command so some of the webhook commands listen and trigger we'll get to those later some stripe commands we can do log tailing and look at the status of stripe so maybe we want to just check the version of stripe CLI that's installed we can say stripe - V note that this one point 3.5 is the version of the stripe CLI that's not the version of your API so you'll want to look in the stripe dashboard for your API version which is usually looks like a date year-month-day separated by hyphens so the other thing we can do here now is we can say stripe status and that'll tell us the status of the API it shows us that all services are online that's great now the next thing on our list is to connect the stripe CLI to our stripe account so when we have access to a browser so in in this environment I can open a browser and successfully authenticate you can say stripe login so we say stripe login and hit enter it shows us a pairing code so reform favored prized right we want to confirm that that matches when we get when we open the browser so we're gonna hit enter to open the browser and then we are shown our pairing code and we can pick which account which of our stripe accounts that we want to use with this with this authentication of the stripe CLI and so I'm gonna say yep that pairing code looks right so I'm going to allow access and we're done so I can just close that tab and go back to the go back to the CLI I'm sorry back to the terminal one thing worth noting too is that you have to be logged into your stripe dashboard in your default browser before you hit open or otherwise you'll have to login for that to work which is totally another valid path ok so now that we've logged in we have access to all of our stripe data directly in the command line so we can say things like stripe plans list and that will list the plans for the stripe account that we just authenticated with so that's pretty cool the way that this works is there are some special keys that are stored in the config so we can look at stripe config dash dash list and that shows us the stripe keys that were created just for this specific setup so our default account is the one that we just authenticated - that's our like demo account what if you wanted to or maybe sometimes you'll have multiple stripe accounts maybe once for test once for production maybe have like a CI account so if you if you need to manage and kind of jump between those different accounts you can use the project name so we can say stripe login - - project project names CI for example to create another config so now we have a new pairing code we hit enter and then when we're we're prompted here we can select the other account so maybe this is the CI account that we want to authenticate with so glitz well that matches our our pairing code that we were just shown so we'll allow access and connect and so we're done here again and go back to the terminal and now if we were if we say stripe config - - list we'll see that we have both a default and a CI config it's pretty handy so if if you are in an environment where you don't have access to a browser and you can't pop that open for example if you're running this on like a CI machine or something that doesn't have access to a browser you can use the config set command so you can say stripe config - - set and then maybe you want to set your live mode API key to something like SK test xxx or SK live in this case and what that will do is just it'll set the key for you so you can go to your stripe dashboard grab some keys that you need to use for C and then use stripe config set as part of maybe your build process and that will that will set your key so we can look again stripe config list to list out our config and you'll see that this has been this has been updated cool so that's really how you get connected with the stripe CLI let's move on to part 2 API resources so you have full access to make API requests to your stripe account directly with the CLI so what I think might make sense is let's try to create a customer and then subscribe that customer to a plan all from the CLI so one thing you might want to know is like what are the resources that are available so we if we say stripe resources that will list out all the different resources that you can access pretty handy so we find customers in here that's great so we can say stripe customers what does that do okay well stripe customers takes an operation and here's the different operations that we can use create delete delete a discount list retrieve update and then some parameters okay cool so what if we say stripe customers create and maybe if we add the - - help flag that'll give us some more information about what we can pass so here in the request parameters these are just like some of the params that we can pass so if we say stripe customers create - - balance or - - coupon we can pass in arguments that are used to create that customer so another thing though that that I want to do is in order for a stripe customer to have like a payment method that's used when they are billed for stripe billing with a subscription they have to have like an invoice settings default payment method which isn't in the list of like default request parameters and so if I'm not if I'm not like a hundred percent sure what options are available to pass to that customer I can say stripe open API and that will open up the API Doc's for you know the AP the full api reference so then once I'm here I can search for customers and go to create customer and I see all the arguments that I can pass in to create a customer which is is pretty neat so we have the payment method that'll be important because we want to attach a payment method that we're going to use for billing and then down here under invoice settings we have the invoice settings default payment method so this is a nested argument so I want to show you both how to send those like top level requests args and then also some nested ones another thing to point out while we're here in the API ref is that stripe CLI is one of the like language options that you can use from the drop-down to see what the format of the request might look like so maybe for your integration if you're building in Ruby this is the code that you would use to create a customer with a description and with the stripe CLI it looks just like this so stripe customers create - - description and a description okay so let's head back over to the terminal and we'll say stripe customers create and we'll give this this customer and email and it'll be just like CLI test example comm and let's also give them a payment method which is p.m. Card Visa so this payment method right here is going to be the token of the payment method that you tokenized on the client with stripe GS or stripe iOS or stripe Android but when you're in test mode you can use these test tokens so one of what while you're looking at the test cards in the docs you'll see these four two four two numbers which are really common but then these in these other tabs you have options to use these shortcut tokens that are pre-built in order to test different scenarios for you so I'm just gonna use this p.m. card visa as sort of the the card that we're going to use on this customer so bypassing the payment method at the top level I'm attaching the payment method to the customer and then I also wanted to pass this nested invoice settings because it's nested you can't really use like the the - - argument for the request argh so we have to say - D and then I can say invoice settings default payment method like this because the default payment method is nested inside of the invoice settings argument so it's kind of like an attribute style the same way that you would see with curl or with like a query string parameter and I can again pass p.m. card visa so now this is actually going to create a customer through the API and we get back the data at the JSON data for that newly created customer we have this ID we have this customer ID which is great so the next thing we can do is we can say like stripe customers retrieve and then pass in that customer ID we get back the same data super handy so the next thing I want to do is create a subscription now that we have a customer they have payment methods they have a payment method set and they have their invoice settings default payment method set that's great so now we can say stripe subscriptions create and again if we do - - help that'll tell us all the different things that we can pass in when creating a subscription so tons of different options for creating subscriptions for now I just need customer and then I need to tell it like which plan to subscribe to so I'm gonna say stripe customer oops we lost our ID here let's go grab that customer ID and oops subscriptions stripe subscriptions create customer and then we also want to say dash D items so this is how we set the plan plan equals and then I have a I have a plan with the ID movies setup in here so I can say create a subscription for this new customer with the plan movies and look at that I've got a new active subscription I've charged the customer and it's successfully up and running and this is so cool I love that you can do everything directly from the command line it's so neat so now we have this latest invoice so we something we might do just grab that ID and say you know like stripe invoices retrieve and then pass in the invoice ID Justice a is the status of that invoice paid and it is so that's super handy way to kind of just like poke around and explore we've created a customer we subscribed them to a plan and so this is this is one of the examples that you can go through to like interact with those resources directly through the API with the stripe CLI so you can kind of think of the CLI as a command line interface in your dashboard as a graphical user interface that are really helpful when trying to determine what what things you're building for your integration ok the next thing I want to show is that not all of the API endpoints are accessible with your restricted keys that come with the CLI for instance if you have connected accounts so if you're a platform and you're debugging with connected accounts and you try to say something like stripe accounts list you'll receive this error that says the provided key arcade test blah blah blah does not have the required permission for this endpoint so in this case what I like to do is pass in my key explicitly with - - API key and then I store my my secret key which is not the restricted key but the secret key I stored in an environment variable because I'm doing this a lot but you could pass in your secret key right here directly and that would use your secret key instead of the restricted key and here we get all of the connected account data back so that's pretty neat ok so that's how you can pass sort of an API key if you're restricted key doesn't have enough permission ok the next thing I want to do is show you how to pair this with JQ so what is JQ j q is a command line tool sort of like said but for processing json directly in the command line very handy and because the output of a lot of these API resource operations is is JSON data we can interact with that json data directly with JQ so if we say something like stripe customers list maybe maybe our goal is to create like a CSV file of the stripe ID for a customer and their name and email for it for instance so if we say stripe customer list - JQ it's a whole bunch of methods that you can call with JQ and I'd point you to the documentation here so this is this is like the the docs for JQ really really powerful stuff highly recommend highly recommend it so if we take stripe customers list and we pipe it into JQ and we say dot or maybe keys that'll tell us what the keys are in the JSON object that was passed to JQ so there's data has more object and URL so in this case we want to look at data and we know that data is in in an array and we want to pull out the IDS of all the different customers so now we have you know just like a list of customer IDs that's pretty neat JQ you can also like pass JQ lists of or like these long expressions where you can compose different pieces together so we can say dot ID dot name email and then maybe we pipe that to at CSV as part of JQ to create a CSV file that has the stripe ID the name and the email of the customers directly in our account hey maybe we want a few more of those we can say - - limit 100 that's like the maximum so let's let's get the 100 customers here and you see their names and emails directly as a CSV really powerful stuff and pairing the stripe CLI with JQ definitely improves my workflow on the day to day so I wanted to wanted to share that and point that out okay I think that's that's the end of part two let's move on to Act three of today's show which is how to use the stripe CLI with web hooks so oftentimes when you are building a third party integration that uses web hooks you might set up some sort of tunneling software third party tunneling software so that you can provide a public URL to which third party can send post requests that you can then you know test your local webhook server so you want to tunnel from some public domain to your local machine to receive requests but that's like it's kind of tough to get everything all set up and configured so the stripe CLI makes this incredibly simple there is a command called listen and so you can say stripe listen and the stripe listen command is going to establish a direct connection from stripe to your computer and allow stripe to deliver webhook event notifications directly to your machine through through the stripe listen which is it's incredibly powerful and you avoid having to use any third-party tools in order to tunnel the requests from stripe to your to your local development machine now in production you'll have to go set up a real web hook Handler and test it out and test that your public domain is actually available and receiving these post requests from stripe but in development you can use stripe listen to have those events forwarded directly to your local machine now when you're using stripe listen with the stripe CLI you don't actually need to configure any web hook endpoint on in your stripe dashboard or with the API so by by saying stripe listen the CLI is going to configure a web hook endpoint for you inside the dashboard that will forward those those web hook events directly to your machine really cool really powerful stuff so yeah so this is how it works you can just say let's see stripe listen okay and so now stripe is listening for events to happen on our on our stripe account here you see the web hooks secret so if your web hook endpoint handler is doing signature authentic our signature verification you can use this web hook secret to verify those signatures and test your signature verification locally so right now it's just kind of like open waiting for some event to happen so the the first way we can trigger an event to happen or make it making it and it's just by creating some object in the API that will cause an event to happen also while we're here let me show you a bunch of different event types or the where to find the list of event types so if you head back over to the API refugee also do stripe open API and you go to types of events here there's a huge list account dot updated and then this massive massive list customer subscription pending update expired file created invoice that updated so these are all the event types the event types are usually this like dot delimited thing with the object type and then some action that's taken on it very long list so that's where you might find the different types of events so if we wanted to trigger an event one thing that we could do is just make the API call that will cause that event to be fired so if we want a customer dot created event to happen we might just say stripe customers create and that will create a customer and result in a customer dot created event happening and here's the event ID pretty cool sometimes it's difficult to set up all the different API requests you need in order to to trigger a specific event for instance the checkout session completed event is particularly difficult to - to trigger directly from the CLI to automate because there's a couple of different things that need to happen in there you have to have the customer has to go to checkout they have to attach their payment method a customer is created payment intent is created and then succeeded and then a charge succeed then finally the payment intent or the the checkout session completed event fires so in those cases where it's where it can be really difficult to to fire or to test triggering a specific event there are a handful that have already been pre implemented for you as part of the stripe CLI and that is exposed through the trigger command so we can say stripe a trigger and then pass trigger a list or I'm sorry pass trigger the event type that we want to fire so here in the supported events there's a big list and one that I want to show is checkout session completed so if we say stripe trigger checkout session completed event then a whole number of API requests are being made in order to result in this checkout session completed so we see a payment intent was created and then a payment intent is going to succeed will have a charge created and customer created a number of different things so here we have like a whole bunch of events that are firing just so that we can get that checkout session completed event to fire super handy so you kind of just say stripe trigger checkout session completed and then then you can you know you'll you'll see that event mm-hm be published to your your listener here okay one other thing that we can do is we can say stripe listen stripe listen - - events to pass specific event types that we want to listen for so maybe we want to fire up this listener but we don't want to receive all of the firehose of events that are happening on our account so maybe we really only want to listen to checkout session completed and payment intent succeeded or something so we can say stripe - - events and pass in the list of event types to filter down to just those event types that we want to listen to so I'm going to refire the checkout session completed event down here and we'll see that just those two events are displayed so we're kind just like filtering out which events we want to listen to so we get the payment intent succeeded and then we get the checkout session completed event and again these the events that we're listening to are coming from stripe so the stripe trigger command is making API requests to stripe that is creating the objects and when those objects are created and actions are taken the result in events that are being published and those notifications for the events are being published to our account and the account inside of stripe sees that we have a stripe CLI listen listener hooked up and so those event notifications are being delivered directly to our local machine really really cool really handy stuff now the one thing that we haven't done yet is passed this to a local but one more thing before we do that I wanted to show you if you if you add on the dash J this is kind of handy too you can you can output all of the JSON data for an event so if you have if you tack on dash J that'll print out a JSON for the incoming thing so by default also the stripe listen is going to receive events with the the API version which is the default API version of your account so they'll be formatted as the as the data for your your API or for your accounts default API version you can also pass dash L if you want the events in the latest version of the API but you can't specify like a specific API version just like your default accounts API version or the latest and that's that's it so here we get yeah like the in the in the log for our stripe listen we see the JSON output for the events that were published to our endpoint which is super cool super handy okay moving on so this is great we're having events delivered to our local machine but I I'm a web developer and I'm implementing a web hook Handler and I want to know what my web hook endpoint is doing so how can I use the stripe CLI to test my web hook handler so the way this works is we forward we can forward those events that are happening to a local web hook server so I have a web server here that I'm going to fire up and this is gonna be a look this is a local server it's a rail server it's listening on localhost 3000 and so when I say stripe listen I can forward to localhost 3000 slash web hooks this is like the local path to my local server that I want to have those web hooks the web hook notifications published too so we've got our our web hook listener let's again trigger checkout session completed and so we see the payment intent created happened and we got a 200 back from our local - our local webhook server if we go over here we can see in the server log that those post requests are coming in which is pretty neat so we got one post request and then we should get a flood of a bunch more as we receive those other events that happen and then finally we handle this checkout session completed event so that's pretty neat you can you can set up your local your local server with its web hook handler to listen for those events and then receive those a couple a couple other things to add about events and web hooks before we move on and that is these are the IDs of the events so EVT underscore that's the event that just fire this is this check out session check out session completed event and what you can do is one of the API resources that's that's available is the the events resource so we can say stripe events retrieve and we can pass in that event ID okay that's cool we got back all the all the data for that event that's great but let's say that for some reason we our web hook handler had a bug and it failed to process this specific event and what we really want to do is just reprocess the event what you can do is you can say stripe events resend with that specific ID for the event ID and when you hit enter it will retry that event and refire it to your server so that's that's really powerful super fun and something I really wanted to share ok so that that's how you use the stripe CLI to work with web hooks so there's still a couple more things that I wanted to show you trying to make it trying to make it quick okay so stripe serve is a tool for setting up quickly a local file server so let's say you have just like a basic HTML page just want to say like maybe we have like an h1 that says hi stripe integrators okay then we can we can say stripe serve and that will create a local static file server that you can then use to to test your local static files super handy there's a number of different ways you can set up static servers and and things but it just comes for free with stripe CLI which is so nice okay another really cool one that I wanted to share is stripe samples so you can say stripe samples and there's a couple commands here so a stripe sample is a github repository and a collection of code examples for that demonstrate how to integrate some of our products and so there's repositories up on github that you can explore and they generally come with a client directory and a server directory and the server's support generally many different languages so Ruby Python PHP go and so one thing that you can do with stripe samples is directly from the stripe CLI you can pull down a stripe sample and auto have it auto configure your your API keys this is so cool so we can say stripe samples list and this will tell us all the different stripe samples that are available right now so we can we can just go through here and say like oh we can learn how to accept basic card payment that's cool accept a card maybe this set up subscriptions one looks good so I'm gonna say stripe samples create and then pass in stripe samples create and then pass in the name of that stripe sample and that's gonna download and say what which server do you want to use like what is your back-end language Java anode Python Ruby I think I'm feeling like ruby is a good good option today so we have now this new set up subscriptions directory and in here I can just jump right into server and say Ruby server and yeah that fires up another local host for two for two and I can refresh the page and hey look at that I've already caught a stripe sample up and running in like two seconds so you can explore the code that is behind this - right like you can if we jump back over here you can say what does that server look like how is it implemented this is the Ruby code that's backing that server very cool stuff okay so that's stripe samples yeah as a quick recap we covered how to install and configure the CLI how to connect it to your stripe account and use the config command to set API keys if you're if you're using the CLI outside of an environment that has a browser we also showed you how to interact with API objects and create update finally we showed you stripe serve and some stripe samples a couple things we didn't cover that I think are worth mentioning if you just say stripe here and then start playing around with some of these commands completion will allow you to or it generates like the bash completion command so you may have seen I said stripe cuts are like see you and then I hit tab and that'll autocomplete to customers and then I can say re and that'll autocomplete to retrieve so bash completion will help you there it's pretty neat logs log tailing we didn't cover that so that's that's helpful for looking at the logs as they're as they're happening on your account the fixtures command this is like a really advanced version of trigger so you can implement your fixtures as JSON documents that can be a series of API requests that you want to make so you can kind of like build a custom trigger command that can automate a number of different API requests in sequence for you we talked about samples open is you know again to open those quick links in the docs and feedback is a great way for you to tell us what you think about the CLI how we can improve we're we're we're yeah what we're we might be able to to make make this this useful tool even more useful so those are a couple things we did not cover in depth I really hope this was this was useful for you and again this is really just a foundational tool something that's really important that I really want you to know is that you are not alone in building your integration we are here with you and right by your side and we'd be more than happy to help chat chat through any questions you have about your integration or best practices come come hang out with us on IRC we're in the freenode stripe channel otherwise if you wanted to reach out and get assistance for a non-technical question you can always reach out to support stripe comm that's a great Avenue yeah so until next time Cheers you

Channel: Stripe Developers

Views: 32,323

Keywords: stripe, payments, stripe-cli, stripe cli, How to use the Stripe CLI, Stripe CLI, Stripe Command Line, Stripe Payments Command Line Interface, Command Line Interface, @cjav_dev

Id: Psq5N5C-FGo

Length: 34min 18sec (2058 seconds)

Published: Tue Mar 17 2020