Stainless CLI Generator
Product · Developer tool · Engineering & development by Stainless
Your API, now with --help: Generate production-ready CLIs from OpenAPI.
Stainless CLI Generator allows developers to turn OpenAPI specifications into high-performance, native command line tools. It provides a polished, scriptable interface for APIs with features like automatic pagination and shell completions.
Category: Developer Tools
- Platforms
- macOS, Linux, Windows
- Programming languages
- Go, OpenAPI, JSON, YAML
- Editors and tools
- Bash, Zsh, fish, PowerShell
- Deployment
- Self-hosted (Native executable)
- Implementation Language
- Go
- Input Specification
- OpenAPI
- Generates production-ready CLIs from OpenAPI specs
- Compiles to native binaries with no runtime dependencies
- Supports macOS, Linux, and Windows cross-compilation
- Automatic pagination and shell completions included
- Supports dot notation, YAML/JSON inline, and stdin piping
Overview
Stainless CLI Generator is a developer tool that creates production-ready command line interfaces directly from OpenAPI specifications. It is designed for API providers who want to offer high-quality, scriptable tools to their users without the manual effort of building and maintaining them. The generator produces native binaries using Go, ensuring high performance and near-instant startup times with no external runtime dependencies. These binaries are cross-compiled to support macOS, Linux, and Windows across multiple architectures. Each generated CLI features a resource-based structure mirroring the API, automatic pagination, and shell completions for Bash, Zsh, fish, and PowerShell. It handles complex data inputs through dot notation, repeated flags, and stdin piping for JSON or YAML payloads.
Core Generation Features
- OpenAPI-to-CLI Generation: The generator creates command line tools directly from an OpenAPI specification, ensuring the CLI stays in sync with SDKs from a single source of truth.
- Go-Based Performance: Generated tools are built as a wrapper around the Stainless Go SDK, providing high performance and near-instant startup times.
- Native Binaries: The tool compiles to native binaries with no external runtime dependencies, allowing users to run the executable without having Go installed.
- Cross-Platform Support: The generator supports cross-compilation for macOS, Linux, and Windows across multiple architectures.
Command and Argument Parsing
- Resource-Based Structure: Every generated CLI follows a resource-based structure that mirrors the API, such as "project resource method-name --arg".
- Nested Object Support: The tool supports dot notation for nested objects up to two levels deep, simplifying complex command line inputs.
- Repeated Flags for Arrays: Users can pass array values by repeating the same flag multiple times in a single command.
- Inline YAML and JSON: For complex polymorphic types or deep structures, the CLI accepts inline YAML or JSON strings.
- Stdin Payload Piping: The CLI supports piping full JSON or YAML payloads via stdin for complex operations.
Developer Experience
- Automatic Man Pages: The generator automatically creates man pages so that standard Unix help commands work out of the box.
- Shell completions are included for Bash, Zsh, fish, and PowerShell to improve developer productivity.
- Built-in Documentation: The --help flag provides full documentation for any command directly within the terminal.
- Automatic Pagination: The CLI handles automatic pagination for list methods, reducing the manual work required for large data sets.
Use cases
- Developers generate a CLI to provide a scriptable and composable way for users to interact with their APIs.
- API providers use the generator to keep their command line tools automatically in sync with their SDKs from a single source of truth.
- Users pipe complex JSON or YAML payloads via stdin to perform advanced API operations through the command line.
- Teams distribute native binaries to end users on macOS, Linux, and Windows without requiring them to install a specific runtime.
Specifications
- Platforms
- macOS, Linux, Windows
- Programming languages
- Go, OpenAPI, JSON, YAML
- Editors and tools
- Bash, Zsh, fish, PowerShell
- Deployment
- Self-hosted (Native executable)
- Implementation Language
- Go
- Input Specification
- OpenAPI
- Supported OS
- macOS, Linux, Windows
- Supported Shells
- Bash, Zsh, fish, PowerShell
- Binary Type
- Native (No runtime dependencies)
- Argument Syntax
- Kebab-case flags
- Input Formats
- Dot notation, JSON, YAML
- Documentation Type
- Man pages, --help flag
How it works
- Enable CLI Target: Developers enable the CLI target within the Stainless Studio interface.
- Generate from Spec: The platform uses the provided OpenAPI specification to generate a Go-based command line interface.
- Compile Native Binaries: The tool compiles the CLI into native binaries for the desired platforms, including macOS, Linux, and Windows.
- Distribute and Run: End users download and run the fast, efficient executable without needing to install Go or other runtimes.
FAQ
Why is the CLI built using Go?
Stainless chose Go because it compiles to native binaries with no external runtime dependencies and offers near-instant startup times. It also provides excellent cross-compilation support for various operating systems and architectures.
How does the CLI handle complex nested objects?
The generated CLI supports dot notation for objects up to two levels deep. For deeper structures or complex polymorphic types, users can pass YAML or JSON inline or pipe them via stdin.
Does the CLI support shell completions?
Yes, the CLI includes shell completions for Bash, Zsh, fish, and PowerShell, as well as automatically generated man pages for Unix-like systems.
What is the command structure of the generated CLI?
The CLI follows a resource-based structure that mirrors your API, using kebab-case for method names and flags. For example, a command might look like "your-project people retrieve --id 123".
Added by AntSpace from public sources (stainless.com).