# Browse documentation in the terminal

Use the Stripe CLI docs plugin to read the Stripe docs and API reference inside your terminal.

For more details, see the [Stripe CLI reference](https://docs.stripe.com/cli.md).

The `stripe docs` plugin lets you read Stripe documentation and API reference without opening a browser. You can use the command line to access an interactive terminal UI (TUI) for navigating guides, an API reference browser, a webhook event explorer, and unified search.

## Before you begin

- Install the [Stripe CLI](https://docs.stripe.com/stripe-cli/install.md) version 1.11.3 or later
- Install the docs plugin:

```bash
stripe plugin install docs
```

If you need to upgrade the plugin, run:

```bash
stripe plugin upgrade docs
```

## Browse guides 

Run `stripe docs` with no arguments to open the interactive TUI home screen. The home screen shows recently visited pages and available topics sorted by a combination of frequency and recency.

```bash
stripe docs
```

To open a specific topic directly, pass its name as an argument:

```bash
stripe docs payments
stripe docs webhooks
stripe docs checkout
```

The plugin uses fuzzy matching, so partial names and synonyms work too:

```bash
stripe docs customer    # matches the Customers guide
stripe docs refund      # matches the Refunds guide
```

## Browse the API reference 

Use the `api` subcommand to explore the Stripe API reference:

```bash
stripe docs api                         # browse all resources
stripe docs api customers               # show a resource
stripe docs api customers create        # show a specific operation
stripe docs api customers#email         # deep-link to a specific field
```

## Search docs 

Use the `search` subcommand to search across guides and the API reference at once:

```bash
stripe docs search webhooks
stripe docs search "payment methods"
stripe docs search refund
```

Omit the query to open the interactive search TUI, which includes a preview pane:

```bash
stripe docs search
```

## Explore webhook events 

Use the `events` subcommand to explore webhook event types and their payload structure:

```bash
stripe docs events                              # browse all event types
stripe docs events charge.succeeded             # show payload structure
stripe docs events checkout.session.completed   # show payload structure
```

## Open in browser 

Add the `--web` flag (or `-w`) to any command to open the corresponding page on docs.stripe.com instead of in the terminal:

```bash
stripe docs --web payments
stripe docs api customers --web
stripe docs events charge.succeeded --web
```

## Navigate with keyboard shortcuts 

When viewing a page in the interactive TUI, use the following keys to navigate and interact with content:

| Key        | Action                                                    |
| ---------- | --------------------------------------------------------- |
| `j` / `k`  | Scroll line by line                                       |
| `d` / `u`  | Scroll half a page down / up                              |
| `f` / `b`  | Scroll a full page down / up                              |
| `n` / `N`  | Jump to the next / previous section                       |
| `gg` / `G` | Jump to the top / bottom of the page                      |
| `B`        | Breadcrumb teleport (jump to any level in the view stack) |
| `Esc`      | Go back                                                   |
| `q`        | Quit                                                      |
| `/`        | Unified search                                            |
| `y`        | Copy the focused code block                               |
| `Tab`      | Cycle through language tabs                               |
| `L`        | Open the language picker                                  |
| `o`        | Open the current page in the browser                      |
| `R`        | Refresh content from docs.stripe.com                      |
| `x`        | Execute the focused CLI command                           |
| `?`        | Show all keybindings                                      |

## Use structured output formats 

The `--format` flag changes how content is output. Use it for scripting, piping output, or integrating with AI coding agents.

| Format    | Description                                                                                   |
| --------- | --------------------------------------------------------------------------------------------- |
| `json`    | Full machine-readable JSON output                                                             |
| `compact` | Token-efficient plain text, good for LLM context                                              |
| `toon`    | TOON format, approximately 40% fewer tokens than JSON                                         |
| `tool`    | JSON Schema tool definition (for MCP and function calling). Requires `api` plus an operation. |

```bash
stripe docs api customers --format=json
stripe docs api customers --format=compact
stripe docs api customers create --format=tool
stripe docs events charge.succeeded --format=json
```

Use the `--sections` flag to narrow output to specific sections:

```bash
stripe docs api customers --format=json --sections=fields,operations
stripe docs api customers create --format=compact --sections=parameters
```

Use `--filter=required` to show only required fields or parameters:

```bash
stripe docs api customers create --filter=required
```

## Control content source 

The plugin serves content from three sources:

- **LOCAL**: Bundled content included with the plugin (default for most pages).
- **CACHED**: Content previously fetched from docs.stripe.com (reused for 24 hours).
- **LIVE**: Content freshly fetched from docs.stripe.com.

Force a live fetch with `--refresh` or use the `--source` flag to control which source to use:

```bash
stripe docs webhooks --refresh              # fetch fresh content
stripe docs webhooks --source=live          # always fetch latest
stripe docs webhooks --source=local         # use bundled content only (offline)
```

In the TUI, press **R** to refresh the current page and **U** to undo a refresh.

## Use in non-interactive environments 

Use `--no-pager` or `-N` to print output directly to stdout without launching the TUI or a pager. Use this in scripts, CI pipelines, and AI agent sessions:

```bash
stripe docs -N payments                    # print guide to stdout
stripe docs api customers -N              # print API resource to stdout
stripe docs search "refund" --no-pager    # print search results to stdout
```

## Use with coding agents 

We built the `stripe docs` plugin to work with AI coding agents specifically. It provides structured, token-efficient output formats and non-interactive modes so agents can consume Stripe documentation programmatically without requiring a browser, HTML parsing, or interactive prompts.

> For all agent workflows, always combine `-N` (non-interactive) with a `--format` flag. This guarantees clean stdout output with no TUI escape codes or pager prompts.

### Choose flags for agent workflows 

| Flag                        | Purpose                                                                                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-N` or `--non-interactive` | Disable the TUI and pager. Print output directly to stdout.                                                                                             |
| `--no-pager`                | Disable the pager only (it still skips TUI when combined with `--format`).                                                                              |
| `--format=compact`          | Token-efficient plaintext optimized for LLM context windows.                                                                                            |
| `--format=json`             | Full machine-readable JSON. Best for programmatic parsing.                                                                                              |
| `--format=toon`             | TOON format—uses approximately 40% fewer tokens than JSON while retaining structure.                                                                    |
| `--format=tool`             | Emit a JSON Schema tool definition compatible with MCP and function-calling frameworks. It requires an `api` resource and an operation.                 |
| `--filter=required`         | Show only required fields and parameters. This significantly reduces the output size for create and update operations.                                  |
| `--sections=<list>`         | Comma-separated list of sections to include (for example, `parameters`, `fields`, `operations`, `request`). It lets agents request only what they need. |
| `--language=<lang>`         | Restrict code examples to a single language (for example, `python`, `ruby`, `node`, `go`, `java`, `curl`). It eliminates irrelevant samples.            |
| `--source=local`            | Use only bundled content and doesn’t require network calls. It guarantees fast, deterministic output.                                                   |

### Generate tool definitions for function calling 

The `--format=tool` flag produces a JSON Schema definition describing an API operation’s parameters, types, and constraints. You can directly register this output as a tool in MCP servers, OpenAI function-calling, or any agent framework that accepts JSON Schema:

```bash
stripe docs api customers create --format=tool
stripe docs api payment_intents create --format=tool
stripe docs api subscriptions update --format=tool
```

Use this to equip an agent with the ability to call Stripe APIs with correct parameter schemas.

### Build context for LLM prompts 

Use `--format=compact` to produce token-efficient documentation suitable for injecting into an LLM’s context window:

```bash
# Get a compact summary of the Customers resource (fields + operations)
stripe docs api customers -N --format=compact

# Get only the required parameters for creating a PaymentIntent
stripe docs api payment_intents create -N --format=compact --filter=required

# Get a guide in compact format, in a single language
stripe docs -N payments --format=compact --language=python

# Combine sections filter to get only what matters
stripe docs api subscriptions create -N --format=compact --sections=parameters --filter=required
```

### Search and discover from scripts 

Agents can search the full documentation index and receive structured results:

```bash
# Search and get JSON results an agent can iterate over
stripe docs search "webhook signature verification" -N --format=json

# Search for a concept and get compact results
stripe docs search "idempotency" -N --format=compact

# Explore event types for a resource
stripe docs events payment_intent -N --format=json
```

### Inspect webhook event payloads 

When an agent needs to understand what data arrives in a webhook, it can retrieve the full typed payload:

```bash
# Get the payload structure for a specific event
stripe docs events checkout.session.completed -N --format=json

# Get a compact summary of all fields in the event's data.object
stripe docs events invoice.payment_succeeded -N --format=compact
```

### Try advanced examples 

Combine flags for precise, minimal output tailored to specific agent tasks:

```bash
# Agent building a Checkout integration: get only required params in Python
stripe docs api checkout/sessions create -N --format=compact --filter=required --language=python

# Agent needs to know all operations available on a resource
stripe docs api payment_intents -N --format=json --sections=operations

# Agent generating type definitions: get full field schema
stripe docs api customers -N --format=json --sections=fields

# Deep-link to a single field for type information
stripe docs api customers#email -N --format=json

# Get the full event catalog as JSON for dynamic webhook routing
stripe docs events -N --format=json

# Offline mode for deterministic, fast responses (no network)
stripe docs api charges -N --format=compact --source=local

# Pipe compact output into another tool or clipboard
stripe docs api refunds create -N --format=compact --filter=required | pbcopy
```

### Review an example agent workflow 

A typical agent integration pattern looks like this:

1. **Discover**: The agent searches for relevant documentation using `stripe docs search`.
1. **Read**: The agent fetches specific API resource or guide content using `--format=compact` or `--format=json`.
1. **Act**: The agent calls the Stripe API using the parameters it learned.
1. **Register tools**: The agent uses `--format=tool` to dynamically register Stripe operations as callable tools.

```bash
# Step 1: Agent searches for how to create a subscription
stripe docs search "create subscription" -N --format=json

# Step 2: Agent reads the operation details with only required params
stripe docs api subscriptions create -N --format=compact --filter=required --language=node

# Step 3: Agent uses the learned parameters to make the API call
stripe subscriptions create --customer=cus_123 --items[0][price]=price_456

# Register as a tool: agent adds this operation to its tool registry
stripe docs api subscriptions create --format=tool
```

## Command reference 

| Command                                  | Description                                  |
| ---------------------------------------- | -------------------------------------------- |
| `stripe docs`                            | Open the interactive TUI home screen         |
| `stripe docs <topic>`                    | Open a guide or fuzzy-match a query          |
| `stripe docs api`                        | Browse the full API reference                |
| `stripe docs api <resource>`             | Show a specific API resource                 |
| `stripe docs api <resource> <operation>` | Show a specific API operation                |
| `stripe docs api <resource>#<field>`     | Deep-link to a specific field                |
| `stripe docs events`                     | Browse all webhook event types               |
| `stripe docs events <event_type>`        | Show the payload structure for an event type |
| `stripe docs search`                     | Open the interactive search TUI              |
| `stripe docs search <query>`             | Search guides and API reference              |
| `stripe docs version`                    | Print the plugin version                     |