# stripe/stripe-cli architecture

> Architecture diagram of the GitHub repository stripe/stripe-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stripe/stripe-cli
- Repository: https://github.com/stripe/stripe-cli

## Overview

Stripe CLI is a terminal client for testing webhooks, managing Stripe API objects, inspecting request logs, and handling account authentication. The primary workflow starts at the executable, dispatches a command, and uses shared API, configuration, or streaming services to produce a terminal result. The README establishes the major command capabilities; sampled source confirms selected command, authentication, API, and event-processing links. Several command implementations were not sampled, so those subsystem links are documented or marked unverified rather than inferred as direct calls.

Main entry points: [`pkg/cmd/root.go`](https://github.com/stripe/stripe-cli/blob/master/pkg/cmd/root.go) (Command dispatch), [`pkg/cmd/resource/databases.go`](https://github.com/stripe/stripe-cli/blob/master/pkg/cmd/resource/databases.go) (Resource commands), [`cmd/stripe/main.go`](https://github.com/stripe/stripe-cli/blob/master/cmd/stripe/main.go) (Executable), [`pkg/login/client_login.go`](https://github.com/stripe/stripe-cli/blob/master/pkg/login/client_login.go) (Interactive login)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_stripecli["Executable<br/>[main.go]"]
  node_commands["Command dispatch<br/>[root.go]"]
end

subgraph group_account["Account and setup"]
  node_login["Interactive login<br/>[client_login.go]"]
  node_oauth["Device OAuth<br/>[oauth_device.go]"]
  node_profiles["Profiles and config<br/>[profile.go]"]
  node_keyring["Credential storage<br/>[keyring.go]"]
end

subgraph group_api["API and resources"]
  node_resourcecmd["Resource commands<br/>[databases.go]"]
  node_resourcegen["Resource generation"]
  node_spec["API specification<br/>[spec.go]"]
  node_requests["API request handling<br/>[base.go]"]
  node_stripeapi["Stripe API client<br/>[client.go]"]
end

subgraph group_events["Webhook and event testing"]
  node_webhookcmd["Webhook commands<br/>[listen.go]"]
  node_proxy["Webhook forwarding"]
  node_websocket["Event stream client<br/>[client.go]"]
  node_logtail["Request log tailing<br/>[tailer.go]"]
end

subgraph group_support["Shared runtime"]
  node_agentskills["Agent skills<br/>[agentskills.go]"]
  node_sandbox["Sandbox support<br/>[sandbox.go]"]
  node_parsers["Input parsing<br/>[parsers.go]"]
  node_autoupdate["Auto update<br/>[checker.go]"]
end

node_user(("CLI user"))
node_stripe(("Stripe services"))
node_localendpoint(("Local webhook endpoint"))

node_user -->|"runs command"| node_stripecli
node_stripecli -->|"executes"| node_commands
node_stripecli -->|"checks updates"| node_autoupdate
node_commands -.->|"offers login"| node_login
node_login -.->|"authenticates"| node_oauth
node_login -->|"transfers credentials"| node_keyring
node_oauth -->|"uses configuration"| node_profiles
node_commands -.->|"dispatches resource work"| node_resourcecmd
node_resourcegen -->|"reads specification"| node_spec
node_resourcegen -->|"generates commands"| node_resourcecmd
node_resourcecmd -->|"makes API calls"| node_stripeapi
node_requests -.->|"performs requests"| node_stripeapi
node_stripeapi -->|"sends API requests"| node_stripe
node_commands -.->|"dispatches listen"| node_webhookcmd
node_webhookcmd -.->|"forwards events"| node_proxy
node_proxy -->|"acknowledges events"| node_websocket
node_websocket -.->|"streams events"| node_stripe
node_proxy -->|"posts events"| node_localendpoint
node_commands -.->|"offers log tail"| node_logtail
node_logtail -->|"uses event stream"| node_websocket
node_commands -.->|"offers agent skills"| node_agentskills
node_commands -.->|"offers sandbox tools"| node_sandbox
node_resourcecmd -.->|"parses input"| node_parsers
node_user -.->|"receives webhook"| node_localendpoint

click node_stripecli "https://github.com/stripe/stripe-cli/blob/master/cmd/stripe/main.go"
click node_commands "https://github.com/stripe/stripe-cli/blob/master/pkg/cmd/root.go"
click node_login "https://github.com/stripe/stripe-cli/blob/master/pkg/login/client_login.go"
click node_oauth "https://github.com/stripe/stripe-cli/blob/master/pkg/login/oauth_device.go"
click node_profiles "https://github.com/stripe/stripe-cli/blob/master/pkg/config/profile.go"
click node_keyring "https://github.com/stripe/stripe-cli/blob/master/pkg/keyring/keyring.go"
click node_resourcecmd "https://github.com/stripe/stripe-cli/blob/master/pkg/cmd/resource/databases.go"
click node_resourcegen "https://github.com/stripe/stripe-cli/blob/master/pkg/gen/gen_resources_cmds.go"
click node_spec "https://github.com/stripe/stripe-cli/blob/master/pkg/spec/spec.go"
click node_requests "https://github.com/stripe/stripe-cli/blob/master/pkg/requests/base.go"
click node_stripeapi "https://github.com/stripe/stripe-cli/blob/master/pkg/stripe/client.go"
click node_webhookcmd "https://github.com/stripe/stripe-cli/blob/master/pkg/cmd/listen.go"
click node_proxy "https://github.com/stripe/stripe-cli/blob/master/pkg/proxy/webhook_event_processor.go"
click node_websocket "https://github.com/stripe/stripe-cli/blob/master/pkg/websocket/client.go"
click node_logtail "https://github.com/stripe/stripe-cli/blob/master/pkg/logtailing/tailer.go"
click node_agentskills "https://github.com/stripe/stripe-cli/blob/master/pkg/agentskills/agentskills.go"
click node_sandbox "https://github.com/stripe/stripe-cli/blob/master/pkg/sandbox/sandbox.go"
click node_parsers "https://github.com/stripe/stripe-cli/blob/master/pkg/parsers/parsers.go"
click node_autoupdate "https://github.com/stripe/stripe-cli/blob/master/pkg/autoupdate/checker.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stripecli,node_commands,node_user toneBlue
class node_login,node_oauth,node_profiles,node_keyring toneAmber
class node_resourcecmd,node_resourcegen,node_spec,node_requests,node_stripeapi,node_localendpoint toneMint
class node_webhookcmd,node_proxy,node_websocket,node_logtail toneRose
class node_agentskills,node_sandbox,node_parsers,node_autoupdate,node_stripe toneIndigo
```

## Components

### CLI entry

- [Executable](https://github.com/stripe/stripe-cli/blob/master/cmd/stripe/main.go): `cmd/stripe/main.go`
- [Command dispatch](https://github.com/stripe/stripe-cli/blob/master/pkg/cmd/root.go): `pkg/cmd/root.go`

### Account and setup

- [Interactive login](https://github.com/stripe/stripe-cli/blob/master/pkg/login/client_login.go): `pkg/login/client_login.go`
- [Device OAuth](https://github.com/stripe/stripe-cli/blob/master/pkg/login/oauth_device.go): `pkg/login/oauth_device.go`
- [Profiles and config](https://github.com/stripe/stripe-cli/blob/master/pkg/config/profile.go): `pkg/config/profile.go`
- [Credential storage](https://github.com/stripe/stripe-cli/blob/master/pkg/keyring/keyring.go): `pkg/keyring/keyring.go`

### API and resources

- [Resource commands](https://github.com/stripe/stripe-cli/blob/master/pkg/cmd/resource/databases.go): `pkg/cmd/resource/databases.go`
- [Resource generation](https://github.com/stripe/stripe-cli/blob/master/pkg/gen/gen_resources_cmds.go): `pkg/gen/gen_resources_cmds.go`
- [API specification](https://github.com/stripe/stripe-cli/blob/master/pkg/spec/spec.go): `pkg/spec/spec.go`
- [API request handling](https://github.com/stripe/stripe-cli/blob/master/pkg/requests/base.go): `pkg/requests/base.go`
- [Stripe API client](https://github.com/stripe/stripe-cli/blob/master/pkg/stripe/client.go): `pkg/stripe/client.go`

### Webhook and event testing

- [Webhook commands](https://github.com/stripe/stripe-cli/blob/master/pkg/cmd/listen.go): `pkg/cmd/listen.go`
- [Webhook forwarding](https://github.com/stripe/stripe-cli/blob/master/pkg/proxy/webhook_event_processor.go): `pkg/proxy/webhook_event_processor.go`
- [Event stream client](https://github.com/stripe/stripe-cli/blob/master/pkg/websocket/client.go): `pkg/websocket/client.go`
- [Request log tailing](https://github.com/stripe/stripe-cli/blob/master/pkg/logtailing/tailer.go): `pkg/logtailing/tailer.go`

### Shared runtime

- [Agent skills](https://github.com/stripe/stripe-cli/blob/master/pkg/agentskills/agentskills.go): `pkg/agentskills/agentskills.go`
- [Sandbox support](https://github.com/stripe/stripe-cli/blob/master/pkg/sandbox/sandbox.go): `pkg/sandbox/sandbox.go`
- [Input parsing](https://github.com/stripe/stripe-cli/blob/master/pkg/parsers/parsers.go): `pkg/parsers/parsers.go`
- [Auto update](https://github.com/stripe/stripe-cli/blob/master/pkg/autoupdate/checker.go): `pkg/autoupdate/checker.go`

### Other components

- **CLI user**
- **Stripe services**
- **Local webhook endpoint**

## Connections

- CLI user → Executable: runs command
- Executable → Command dispatch: executes (evidence: `cmd/stripe/main.go`)
- Executable → Auto update: checks updates (evidence: `cmd/stripe/main.go`)
- Command dispatch → Interactive login: offers login
- Interactive login → Device OAuth: authenticates
- Interactive login → Credential storage: transfers credentials (evidence: `pkg/login/client_login.go`)
- Device OAuth → Profiles and config: uses configuration (evidence: `pkg/login/oauth_device.go`)
- Command dispatch → Resource commands: dispatches resource work
- Resource generation → API specification: reads specification (evidence: `pkg/gen/gen_resources_cmds.go`)
- Resource generation → Resource commands: generates commands (evidence: `pkg/gen/gen_resources_cmds.go`)
- Resource commands → Stripe API client: makes API calls (evidence: `pkg/cmd/resource/databases.go`)
- API request handling → Stripe API client: performs requests
- Stripe API client → Stripe services: sends API requests (evidence: `pkg/stripe/client.go`)
- Command dispatch → Webhook commands: dispatches listen
- Webhook commands → Webhook forwarding: forwards events
- Webhook forwarding → Event stream client: acknowledges events (evidence: `pkg/proxy/webhook_event_processor.go`)
- Event stream client → Stripe services: streams events
- Webhook forwarding → Local webhook endpoint: posts events (evidence: `pkg/proxy/webhook_event_processor.go`)
- Command dispatch → Request log tailing: offers log tail
- Request log tailing → Event stream client: uses event stream (evidence: `pkg/logtailing/tailer.go`)
- Command dispatch → Agent skills: offers agent skills
- Command dispatch → Sandbox support: offers sandbox tools
- Resource commands → Input parsing: parses input
- CLI user → Local webhook endpoint: receives webhook
