Stripe Cli

If sudo is unavailable, place the binary in the project's bin/ directory and use ./bin/stripe for all subsequent commands.

Step 2: Authenticate

Check authentication status before any operation:

stripe whoami 2>/dev/null

If not authenticated:

• Interactive (default): stripe login — opens browser for OAuth
• API key (non-interactive): stripe login --api-key sk_test_... or set STRIPE_API_KEY env var
• Check project/profile: stripe config --list to see active profile

Always use test mode keys (sk_test_*) during development. Only use --live flag when explicitly requested.

Step 3: Execute the Requested Operation

Read references/commands.md for the full command reference before executing commands.

Common Workflows

Webhook Forwarding (Development)

# Forward all events to local endpoint
stripe listen --forward-to http://localhost:3000/api/webhooks/stripe

# Forward specific events only
stripe listen --events checkout.session.completed,customer.subscription.updated \
  --forward-to http://localhost:3000/api/webhooks/stripe

# Print the webhook signing secret
stripe listen --print-secret

Trigger Test Events

# Trigger a specific event
stripe trigger checkout.session.completed

# Trigger with overrides
stripe trigger payment_intent.succeeded --override payment_intent:amount=2000

# List available trigger events
stripe trigger --help

Resource CRUD

# Create a resource
stripe customers create -d email="[email protected]" -d name="Test User"

# Retrieve by ID
stripe customers retrieve cus_xxx

# List with pagination
stripe customers list --limit 10

# Update
stripe customers update cus_xxx -d name="Updated Name"

# Delete
stripe customers delete cus_xxx

Subscription Management

# Create a product + price
stripe products create -d name="Premium Plan"
stripe prices create -d product=prod_xxx -d unit_amount=999 -d currency=usd \
  -d "recurring[interval]=month"

# Create a subscription
stripe subscriptions create -d customer=cus_xxx -d "items[0][price]"=price_xxx

# Cancel
stripe subscriptions cancel sub_xxx

Inspect Logs

# Tail API request logs
stripe logs tail

# Filter by status
stripe logs tail --filter-status-code-type 4XX

# Filter by path
stripe logs tail --filter-request-path /v1/charges

Step 4: Verify Results

After any mutating operation:

1. Confirm the response shows expected data
2. For webhook forwarding, verify the local endpoint received events
3. Use stripe get /v1/<resource>/<id> to double-check resource state

Error Handling

Safety Rules

• Never use --live unless the user explicitly requests it. Default to test mode.
• Never expose API keys in logs, files, or output. Use env vars or stripe login.
• Always confirm before destructive operations like deleting customers, canceling subscriptions, or modifying live resources.
• Webhook secrets are ephemeral — a new stripe listen session generates a new signing secret. Ensure the app uses the current one.