CLI

CLI is experimental. Contact us at support@stainless.com for assistance.

The Stainless CLI generator creates command line tools from your OpenAPI specification. Generated CLIs include automatic pagination, interactive TUI explorer, and man pages. The CLI wraps your Go SDK with command line argument parsing.

Example repositories:

• stainless-api/stainless-api-cli

Considerations

A CLI tool helps your users interact with your API from the terminal and integrate it into shell scripts and automation workflows. CLI tools are particularly valuable for developer-focused APIs and CI/CD integrations.

Before generating a CLI tool, be aware of the following requirements:

Go SDK dependency

The CLI generator creates a wrapper around your Go SDK, so Go must be included as one of your SDK targets and you must have a public-facing repository for your Go SDK.

Argument structure limitations

Command line interfaces have limitations when passing deeply nested structures as arguments. The generator makes flags as ergonomic as possible, but you may need to provide deeply nested parameters in JSON or YAML format.

Configuration

To generate a CLI tool, add the cli target to your Stainless configuration file.

The CLI generator creates a wrapper around your Go SDK, so you’ll need to enable both targets:

targets:
  go:
    package_name: github.com/my-company/my-sdk-go
    production_repo: my-org/my-sdk-go
  cli:
    binary_name: my-tool
    production_repo: my-org/my-tool
    edition: cli.2025-10-08

For a complete list of configuration options, see the CLI target reference.

Usage

Test locally

To test your CLI tool before release:

1. Clone your CLI staging repository
2. Follow the instructions in the repository’s README.md to run the tool with Go

Basic usage

The basic structure of your command line tool follows this format:

my-tool [resource [sub-resource...]] method-name --method-arg value

For example, if your Stainless configuration has the following resources:

resources:
  $client:
    methods:
      current_status: get /status
  people:
    methods:
      retrieve: get /person/{id}
      create: post /person
      list: get /people

Then your generated CLI tool can be used like this:

my-tool current-status
# Output: {"status": "Up and running!"}

my-tool people create --job "President" \
    --name.full-name "Abraham Lincoln" \
    --name.nickname "Abe Lincoln"

my-tool people retrieve --id 123

my-tool people list

Note that method names like current-status and flags like --full-name use kebab-case, which is conventional for command line tools.

Argument parsing

Get help for any command using the --help flag:

# General help
my-tool --help

# Help for a specific endpoint
my-tool people create --help

You can also pipe JSON or YAML data as body parameters:

my-tool people create <<YAML
name:
  full_name: Abraham Lincoln
  nickname: Honest Abe
job: President
YAML

# Or from a file:
cat person.json | my-tool people create

Top-level flags

Built-in top-level flags:

• --help, -h: Show help message and exit
• --version, -v: Print version and exit
• --base-url: Provide a base URL for the API backend
• --format=...: Change output formatting (see below)
• --debug: Show debug information for HTTP requests and responses

Output formatting

The default output format is formatted and syntax-highlighted JSON. You can select different formats using the --format flag:

• --format=auto: Automatically chosen format (currently defaults to json)
• --format=json: JSON with autoformatting and syntax highlighting
• --format=jsonl: JSON formatted to fit on a single line
• --format=raw: Exact raw JSON response from server
• --format=yaml: Response in YAML format
• --format=pretty: Human-readable format similar to YAML with a box
• --format=explore: Interactive TUI explorer for browsing nested data

Paginated endpoints

For paginated endpoints, your CLI supports automatic pagination. Items are lazily streamed and sent to your user’s terminal pager (e.g., $PAGER or less). New pages load automatically as the user scrolls.

The CLI respects HTTP 429 (too many requests) responses and throttles according to your response headers.

Man pages

Published CLI tools include automatically generated man pages. Users can run man my-tool to see the full usage manual.

When running locally, generate man pages by running ./scripts/run @manpages, which creates a compressed file in ./man/man1/, viewable with man ./man/man1/my-tool.1.gz.

Editions

Editions allow Stainless to make improvements to SDKs that aren’t backwards-compatible. You can explicitly opt in to new editions when you’re ready. See the SDK and config editions reference for more information.

cli.2025-10-08

• Initial edition for CLI (used by default if no edition is specified)

Publishing to Homebrew

Stainless handles formula creation and management when you publish to Homebrew.

Before publishing, you need to link a production repository where Stainless will push your CLI code.

Create a Homebrew tap repository

1. Create a public GitHub repository named homebrew-tools under your organization (or any name starting with homebrew-).

The repository name must start with homebrew- according to Homebrew conventions.

Generate a GitHub Personal Access Token

1. Click on your account profile picture > Settings > Developer Settings > Personal Access Tokens > Fine-grained tokens > Generate new token.
2. Choose your organization as the resource owner.
3. Set “No expiration” to avoid regular renewal (recommended), or choose an expiration date.
4. Choose “Only select repositories” and select the homebrew repository you created.
5. Add permissions for “Contents” and “Pull requests” with read and write access.
6. Generate the token and save it securely.

Add the token to your production repo

1. In your CLI tool’s production repository, navigate to Secrets and variables > Actions > New repository secret. The URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
2. Add a new secret named HOMEBREW_TAP_GITHUB_TOKEN with your token.

Update your Stainless config

Update the Stainless config and save:

targets:
  cli:
    publish:
      homebrew:
        tap_repo: your-org/homebrew-tools
        homepage: https://example.com
        description: The official CLI for YourOrg.

Install and use

Once published, users can install your CLI using:

brew tap your-org/tools
brew install your-tool
# or more concise:
brew install your-org/tools/your-tool