DOCSEARCHbyAlgolia
Submit Docs

Stripe CLI

repository·master·Indexed 24 days ago

https://github.com/stripe/stripe-cli

A terminal-based tool for developers to build, test, and manage Stripe integrations. It provides capabilities for webhook testing, real-time API log tailing, direct manipulation of Stripe API objects, and access to Stripe's official OpenAPI specification.

Tokens
32.4K
Snippets
58
Records
244
Agent score
83%

What's inside stripe-cli

  1. Access Stripe's OpenAPI Specification

    master
    The api/openapi-spec/ directory contains the official OpenAPI specification for Stripe's API. Developers can use this specification to understand the full surface of Stripe's API, including endpoints, request/response schemas, and authentication requirements, which is useful for generating client libraries or validating API interactions.

  2. Use the palette component for TUI command palettes

    master

    The palette package provides a Bubble Tea component designed for building command palettes. It supports pluggable modes that allow you to:

    • Perform fuzzy filtering on a static list of items.
    • Dispatch asynchronous searches.
    • Mix both filtering and async searching using different prefixes.

    Each palette.Mode manages its own Match logic, Items retrieval, and can optionally include an async Search function or typeable Facets.

    import "github.com/stripe/stripe-cli/pkg/docs/internal/palette"

var commands = []palette.Item{
    palette.Command{Name: "Open file"},
    palette.Command{Name: "Save"},
    palette.Command{Name: "Quit"},
}

mode := palette.Mode{
    Name: "commands",
    Items: func(_ palette.Model, q string) []palette.Item {
        return palette.FilterFuzzy(commands, q)
    },
}

p := palette.New(palette.WithModes(mode))

  3. Configure palette modes

    master

    A palette.Mode defines how items are presented and filtered within the palette. You can configure a mode by providing a Name and an Items function. The Items function is called with the current palette.Model and the user's query string q, returning a slice of palette.Item.

    Key capabilities of a mode include:

    • Match: Logic for matching queries to items.
    • Items: A function to return the list of items based on the query.
    • Search: An optional asynchronous search function.
    • Facets: Optional typeable facets for filtering.

  4. How the Stripe CLI command structure works

    master

    The Stripe CLI is organized into individual commands and subcommands. Most commands are implemented as standalone files in the source, while complex commands use subdirectories to house their subcommands (e.g., stripe plugin install).

    If you attempt to run a command that has not been registered in the CLI's root command structure, the tool will return an "unknown command" error.

  5. How the Stripe CLI handles API requests

    master
    All HTTP requests made by the CLI to the Stripe API are routed through a centralized requests package. This package utilizes a Client to wrap native HTTP calls and execute the PerformRequest method, ensuring consistent communication with the Stripe backend.

  6. Understand auto-generated resource commands

    master

    The Stripe CLI includes many auto-generated commands that correspond to base Stripe API resources (e.g., charges, customers).

    These resource commands do not contain logic themselves; instead, they act as namespaces for Operation Commands. To interact with a resource, you must use an operation subcommand such as retrieve, create, or list under that resource's namespace.

  7. Use operation commands for API resources

    master

    For any auto-generated resource command, you can perform CRUD operations using specific operation subcommands. These subcommands are built to wrap generic HTTP calls and responses to the Stripe API.

    Common operation patterns include:

    • stripe <resource> create
    • stripe <resource> retrieve
    • stripe <resource> list

  8. How plugin runtime installation works

    master

    When a user runs stripe plugin install <name>, if the plugin manifest specifies a Runtime requirement, the Stripe CLI performs the following steps:

    1. Download: Fetches the required Node.js version from https://nodejs.org/dist.
    2. Verify: Validates the download using hardcoded SHA256 checksums.
    3. Extract: Unpacks the runtime into ~/.config/stripe/runtimes/node/<version>/.
    4. Deduplicate: If another plugin already installed that specific Node.js version, the CLI reuses the existing installation instead of downloading it again.

    Example Installation Output:

    $ stripe plugin install generate
downloading Node.js v20.18.1 runtime...
installing 'generate' v1.0.0...
✔ installation of v1.0.0 complete.

  9. Plugin runtime directory structure

    master

    The Stripe CLI manages plugins and their runtimes in the ~/.config/stripe/ directory. The structure follows this pattern:

    • Plugins: ~/.config/stripe/plugins/<plugin-name>/<version>/<binary>
    • Runtimes: ~/.config/stripe/runtimes/node/<version>/bin/node
    ~/.config/stripe/
├── plugins/
│   └── generate/
│       └── 1.0.0/
│           └── stripe-cli-generate
└── runtimes/
    └── node/
        └── 20.18.1/
            └── bin/
                └── node

  11. How to add new Canary Tests

    master

    When adding new end-to-end tests to the suite, follow these guidelines:

    1. File Placement: Add test functions to the appropriate file based on the feature:

      • basic_test.go: Version, help, completion.
      • api_test.go: API resource tests.
      • listen_test.go: Webhook listener tests.
      • logs_test.go: Log streaming tests.
      • config_test.go: Configuration tests.
      • login_test.go: Authentication tests.
      • v2_api_test.go: V2 resource/raw API tests.
      • data_reporting_test.go: Data & reporting (analytics) commands (requires data_analytics_canary tag).

    2. Naming & Requirements:

      • Use the TestOffline prefix for tests that do not require an API key.
      • Use the TestAPI prefix for tests requiring an API key, and call requireAPIKey(t) within the test.

    3. Best Practices:

      • Use isolated config directories via testutil.CreateTempConfigDir().
      • Always use sanitized logging to prevent secret exposure. Use fatalf(), errorf(), and logSanitizedf() instead of standard Go testing methods like t.Fatalf() or t.Logf().

    Example Test Implementation

    func TestOfflineNewFeature(t *testing.T) {
    runner := getRunner(t)

    result, err := runner.Run("new-command", "--flag")
    if err != nil {
        fatalf(t, "Failed to run command: %v", err)
    }

    if result.ExitCode != 0 {
        errorf(t, "Expected exit code 0, got %d", result.ExitCode)
    }
}

func TestAPINewFeature(t *testing.T) {
    runner := getRunner(t)
    requireAPIKey(t)

    runner = runner.WithEnv(map[string]string{
        "STRIPE_API_KEY": testutil.GetAPIKey(),
    })

    result, err := runner.Run("api-command")
    // Use sanitized logging for output that may contain secrets
    logSanitizedf(t, "Result: %s", result.Stdout)
}

  12. Install the Stripe CLI on Windows

    master

    Windows users can install the CLI using WinGet or Scoop.

    # WinGet
winget install Stripe.StripeCLI

# Scoop
scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git
scoop install stripe