Stripe CLI for coding agents

When you give a coding agent shell access to a Stripe project, it can use the Stripe CLI to run Stripe commands and send test events to a local webhook handler. A webhook is an HTTP request that Stripe sends to your code when an event, such as a successful payment, occurs. Use the CLI to check whether your local code handles those requests. Commands that create test events still add data to your Stripe sandbox, a test environment separate from live data.

The Stripe CLI documentation covers webhook forwarding and test events. Stripe also documents stripe agent setup, which detects supported coding agents and installs Stripe tooling for them. The example below uses the CLI to deliver a test payment event to a local endpoint.

Install and authenticate

The installation page lists an install script for each operating system and an npm package. With npm, run:

npm install -g @stripe/cli@latest

Then sign in:

stripe login

The CLI shows a pairing code and opens the Stripe Dashboard in your browser. The login reference says you confirm the code there and choose which accounts and sandboxes the CLI can use, and whether it gets live mode access. For agent work, approve sandbox access only. Finish authorization there, outside the agent prompt. For CLI versions newer than v1.50.0, an Administrator or IAM Admin must first turn on CLI access in the Dashboard settings. After approval, the CLI keeps its credentials in your operating system's secure credential store when one is available. Do not paste a secret key or browser credentials into a prompt or repository file.

If you want Stripe to configure a supported coding agent, run:

stripe agent setup

The agent setup reference says this command detects the supported agents, which its --client flag lists as claude-code, codex and cursor. For each one, it installs the Stripe plugin and skills. It also sets up the Stripe MCP server. Add --json first to see the planned actions without making changes, and review what it changes in your agent configuration. Stripe’s separate agent skills provide reusable instructions for Stripe development; they guide an agent but do not replace CLI authentication.

Forward a test event locally

Start your local service with a webhook route ready to receive requests. In one terminal, start the Stripe listener and replace the example URL with your service’s local address and route:

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

Here, localhost:4242/webhook is a placeholder. The listener connects to Stripe and forwards incoming test events to that address. It prints a webhook signing secret, which your handler uses to verify forwarded events. The listen reference says this secret stays the same when you restart the command. Store the secret in a local environment variable or another secret store, and configure your handler to use it. Do not commit it or include it in an agent prompt.

In a second terminal, ask the CLI to create a test event:

stripe trigger payment_intent.succeeded

payment_intent.succeeded names a Stripe test event. The trigger reference says the CLI creates the API objects the event needs, so this example also triggers payment_intent.created. The listener forwards the events to the local route. Check your service’s logs or test output to confirm that the handler received and processed the request. The exact output depends on the CLI version and your local server.

This example makes a network request and creates test data in Stripe. It does not charge a real card or send a live payment. The listen reference says requests run in a sandbox unless you add --live. Do not give an agent live access by adding live-mode flags or credentials to its commands unless the task specifically requires a live account action and you have approved it.

Give the agent a bounded task

A prompt can ask the agent to inspect the local webhook handler and run the test event, while stating what it must not change:

Inspect the webhook handler for payment_intent.succeeded. Start the local service using the project’s documented command, forward Stripe test events to localhost:4242/webhook, and trigger that test event. Report whether the handler processes it. Do not use live mode, change Stripe account settings, or edit code without asking me first.

Replace the example route and port with values from your project. If the service requires a local environment file, configure it before starting the agent and keep its secrets out of the prompt. The agent can run the documented CLI commands, but the local handler still needs valid signature-verification setup to accept the forwarded event.

Configure an agent with the CLI’s stripe agent setup command, then use listen and trigger to test Stripe behavior. The login flow changed after v1.50.0, so check the CLI releases when a command or supported agent differs from your installed version.