Generate a production-ready command line tool (CLI) from your OpenAPI spec.

The Stainless CLI generator creates a command line tool from your OpenAPI specification. Your generated CLI includes 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

A CLI tool lets 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 creates ergonomic flags, but you may need to provide deeply nested parameters in JSON or YAML format.

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.

To test or install the CLI locally, you need Go version 1.22 or later installed.

Verify your installation:

go version
# go version go1.22.0 darwin/arm64

Understanding where Go installs binaries

When you run go install, the binary is placed in your Go bin directory:

• Default location: $HOME/go/bin (or $GOPATH/bin if GOPATH is set)
• Check your path: Run go env GOPATH to see the base directory

If commands aren’t found after installation, add the Go bin directory to your PATH:

# Add to your shell profile (.zshrc, .bashrc, etc.)
export PATH="$PATH:$(go env GOPATH)/bin"

To test your CLI tool before release:

1. Clone your CLI staging repository
2. Navigate to the repository directory
3. Run the CLI using the provided script:

./scripts/run [resource] [command] [flags]

For example, to test an endpoint:

./scripts/run people retrieve --id 123

Installing locally

To build and install the CLI to your Go bin directory:

After installation, run the CLI directly:

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.

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

To pass files to your API, you can use the @myfile.ext syntax:

my-tool people update --photo @abe.jpg

Files can also be passed inside JSON or YAML blobs:

my-tool people update --profile '{pic: "@abe.jpg"}'
# Equivalent:
my-tool people update <<YAML
profile:
  pic: "@abe.jpg"
YAML

If you need to pass a string literal that begins with an @ sign, you can escape the @ sign to avoid accidentally passing a file.

my-tool people update --username '\@abe'

For JSON endpoints, the CLI tool does filetype sniffing to determine whether the file contents should be sent as a string literal (for plain text files) or as a base64-encoded string literal (for binary files). If you need to explicitly send the file as either plain text or base64-encoded data, you can use @file://myfile.txt (for string encoding) or @data://myfile.dat (for base64-encoding). Note that absolute paths will begin with @file:// or @data://, followed by a third / (for example, @file:///tmp/file.txt).

my-tool upload-arbitrary-file --file @data://file.txt

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

Generated CLIs support configuration through environment variables. The environment variable names are defined in your Stainless configuration under client_settings.opts.

For example, if your config includes:

client_settings:
  opts:
    api_key:
      type: string
      read_env: MY_TOOL_KEY

Then the CLI reads authentication from the MY_TOOL_KEY environment variable.

MY_TOOL_KEY=sk_my_api_key_abc123xyz my-tool people retrieve --id 123
# Or export to reuse
export MY_TOOL_KEY=sk_my_api_key_abc123xyz
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

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 (see below)

The --format=explore option opens an interactive terminal UI for navigating complex JSON responses. This is useful for exploring deeply nested data structures.

my-tool people retrieve --id 123 --format=explore

Keyboard shortcuts:

The explorer uses your system pager (configured via the PAGER environment variable, defaulting to less) for scrolling through large datasets.

Use the --transform flag to filter or reshape JSON responses using GJSON query syntax. This is useful for extracting specific fields or navigating nested structures.

# Extract just the name field
my-tool people retrieve --id 123 --transform "name"
# Get the first item from an array
my-tool people list --transform "items.0"
# Extract multiple fields
my-tool people retrieve --id 123 --transform "{name,job}"
# Filter array items
my-tool people list --transform 'items.#(job=="President")#'

Common GJSON patterns:

Use --transform-error to apply the same transformation to error responses.

For paginated endpoints, your CLI supports automatic pagination. The CLI lazily streams items 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.

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.

Generated CLIs include tab completion support for Bash, Zsh, and Fish shells. Completions are included in Homebrew installations automatically.

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.

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

Once published, users can install your CLI without having Go installed on their machine. Stainless uses GoReleaser to build cross-platform binaries and publish releases.

For details on how Stainless opens Release PRs and manages versioning, see Versioning and releases.

After publishing a release, your users have several installation options:

Homebrew (macOS/Linux) — Recommended for most users:

brew install your-org/tools/your-tool

Pre-built binaries — Download from GitHub releases for any platform.

Go users — Install directly with Go:

go install github.com/your-org/your-tool/cmd/your-tool@latest

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

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

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

macOS requires applications to be notarized by Apple before users can run them without security warnings. Stainless uses GoReleaser’s notarization support to handle this process during builds, which requires an Apple Developer account. See the GoReleaser notarization documentation for details on obtaining the necessary credentials.

You’ll need two files from Apple:

1. Signing certificate (.p12) — Export your “Developer ID Application” certificate from Keychain Access
2. App Store Connect API key (.p8) — Create an API key at App Store Connect with the “Developer” role

Configure your CLI repository with these GitHub Actions secrets:

bash ./setup-notarize.sh org/repo

#!/usr/bin/env bash
# Configure a GitHub repository with Apple notarization secrets for GoReleaser.
#
# Usage:
#   ./setup-notarize.sh [OWNER/REPO]
#
# If OWNER/REPO is omitted, the current git remote origin is used.
# Requires the `gh` CLI to be authenticated.
set -euo pipefail
# ── helpers ──────────────────────────────────────────────────────────────────
die()  { echo "error: $*" >&2; exit 1; }
info() { echo "  $*"; }
ask()      { printf "%s: " "$1" >&2; read -r  REPLY; echo "${REPLY/#\~/$HOME}"; }
ask_path() { printf "%s: " "$1" >&2; read -re REPLY; echo "${REPLY/#\~/$HOME}"; }
ask_secret() {
    printf "%s: " "$1" >&2
    read -rs REPLY
    echo >&2
    echo "$REPLY"
}
# ── repo detection ────────────────────────────────────────────────────────────
if [[ $# -ge 1 ]]; then
    REPO="$1"
else
    REMOTE=$(git remote get-url origin 2>/dev/null) || die "No git remote 'origin' found and no OWNER/REPO argument given."
    # Normalize SSH or HTTPS URL → owner/repo
    REPO=$(echo "$REMOTE" \
        | sed -E 's|git@github\.com:||; s|https://github\.com/||; s|\.git$||')
fi
[[ "$REPO" == */* ]] || die "Could not parse a valid OWNER/REPO from: $REPO"
# ── confirm gh is available and authed ───────────────────────────────────────
command -v gh &>/dev/null || die "'gh' CLI not found. Install it: https://cli.github.com"
gh auth status &>/dev/null  || die "Not logged in to GitHub. Run: gh auth login"
cat <<END
Setting up Apple notarization secrets for: $REPO
END
# ── collect credentials ───────────────────────────────────────────────────────
cat <<END
Step 1 of 3 — Signing certificate (.p12)
  Export your 'Developer ID Application' certificate from Keychain Access
  as a .p12 file, then supply the path and its password below.
END
P12_PATH=$(ask_path "  Path to .p12 file")
[[ -f "$P12_PATH" ]] || die "File not found: $P12_PATH"
MACOS_SIGN_P12=$(base64 < "$P12_PATH")
MACOS_SIGN_PASSWORD=$(ask_secret "  .p12 password (hidden)")
openssl pkcs12 -in "$P12_PATH" -passin "pass:$MACOS_SIGN_PASSWORD" -noout 2>/dev/null \
    || die "Could not open .p12 with that password — check the file and password and try again."
cat <<END
Step 2 of 3 — App Store Connect API key (.p8)
  Create an API key at https://appstoreconnect.apple.com/access/api
  with 'Developer' role. Download the .p8 file.
END
P8_PATH=$(ask_path "  Path to .p8 file")
[[ -f "$P8_PATH" ]] || die "File not found: $P8_PATH"
MACOS_NOTARY_KEY=$(base64 < "$P8_PATH")
_p8_base=$(basename "$P8_PATH" .p8)
if [[ "$_p8_base" == AuthKey_* ]]; then
    MACOS_NOTARY_KEY_ID="${_p8_base#AuthKey_}"
    info "Key ID detected from filename: $MACOS_NOTARY_KEY_ID"
else
    MACOS_NOTARY_KEY_ID=$(ask "  Key ID (10-character identifier from App Store Connect)")
fi
MACOS_NOTARY_ISSUER_ID=$(ask "  Issuer ID (UUID shown on the API Keys page)")
cat <<END
Step 3 of 3 — Uploading secrets to GitHub...
END
set_secret() {
    local name="$1"
    local value="$2"
    printf "  %-30s" "$name"
    if printf '%s' "$value" | gh secret set "$name" --repo "$REPO" --body - >/dev/null; then
        echo "set"
    else
        echo "FAILED"
        return 1
    fi
}
set_secret MACOS_SIGN_P12          "$MACOS_SIGN_P12"
set_secret MACOS_SIGN_PASSWORD     "$MACOS_SIGN_PASSWORD"
set_secret MACOS_NOTARY_KEY        "$MACOS_NOTARY_KEY"
set_secret MACOS_NOTARY_KEY_ID     "$MACOS_NOTARY_KEY_ID"
set_secret MACOS_NOTARY_ISSUER_ID  "$MACOS_NOTARY_ISSUER_ID"
cat <<END
Done. The following GitHub Actions secrets are now configured on $REPO:
  MACOS_SIGN_P12           – base64-encoded .p12 signing certificate
  MACOS_SIGN_PASSWORD      – password to unlock the .p12
  MACOS_NOTARY_KEY         – base64-encoded .p8 App Store Connect API key
  MACOS_NOTARY_KEY_ID      – key identifier (e.g. XXXXXXXXXX)
  MACOS_NOTARY_ISSUER_ID   – issuer UUID from App Store Connect
Reference these in your GoReleaser config:
  https://goreleaser.com/customization/sign/notarize/
END

After configuring the GitHub secrets, add the following to your CLI project’s .goreleaser.yml file:

notarize:
  macos:
    - enabled: '{{ isEnvSet "MACOS_SIGN_P12" }}'
      ids: [macos]
      sign:
        certificate: "{{.Env.MACOS_SIGN_P12}}"
        password: "{{.Env.MACOS_SIGN_PASSWORD}}"
      notarize:
        issuer_id: "{{.Env.MACOS_NOTARY_ISSUER_ID}}"
        key_id: "{{.Env.MACOS_NOTARY_KEY_ID}}"
        key: "{{.Env.MACOS_NOTARY_KEY}}"

If you don’t have an Apple Developer account, GoReleaser supports an alternate workaround that uses a post-install hook to remove the macOS quarantine attribute. See GoReleaser’s signing and notarizing documentation for details.