https://github.com/stainless-api/stainless-api-cli
https://github.com/stainless-api/stainless-api-cli
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/stainless-api/stainless-api-cli
- Owner: stainless-api
- License: apache-2.0
- Created: 2025-04-02T07:59:22.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-05T21:52:09.000Z (3 months ago)
- Last Synced: 2026-03-05T23:27:09.697Z (3 months ago)
- Language: Go
- Size: 1010 KB
- Stars: 18
- Watchers: 1
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Stainless CLI
> [!CAUTION]
>
> The CLI is unstable and the API may change. Please feel free to use it locally, but don't build scripts against it.
The official CLI for the [Stainless REST API](https://www.stainless.com/docs/getting-started/quickstart-cli).
It is generated with [Stainless](https://www.stainless.com/).
## Installation
### Installing with Homebrew
```sh
brew install stainless-api/tap/stl
```
### Installing with Go
To test or install the CLI locally, you need [Go](https://go.dev/doc/install) version 1.22 or later installed.
```sh
go install 'github.com/stainless-api/stainless-api-cli/cmd/stl@latest'
```
Once you have 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:
```sh
# Add to your shell profile (.zshrc, .bashrc, etc.)
export PATH="$PATH:$(go env GOPATH)/bin"
```
### Running Locally
After cloning the git repository for this project, you can use the
`scripts/run` script to run the tool locally:
```sh
./scripts/run args...
```
## Usage
The CLI follows a resource-based command structure:
```sh
stl [resource] [flags...]
```
```sh
stl builds create \
--api-key 'My API Key' \
--project stainless \
--revision main
```
For details about specific commands, use the `--help` flag.
### Environment variables
| Environment variable | Required | Default value |
| -------------------- | -------- | ------------- |
| `STAINLESS_API_KEY` | no | `null` |
### Global flags
- `--api-key` (can also be set with `STAINLESS_API_KEY` env var)
- `--project`
- `--help` - Show command line usage
- `--debug` - Enable debug logging (includes HTTP request/response details)
- `--version`, `-v` - Show the CLI version
- `--base-url` - Use a custom API backend URL
- `--format` - Change the output format (`auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml`)
- `--format-error` - Change the output format for errors (`auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml`)
- `--transform` - Transform the data output using [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)
- `--transform-error` - Transform the error output using [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)
### Passing files as arguments
To pass files to your API, you can use the `@myfile.ext` syntax:
```bash
stl --arg @abe.jpg
```
Files can also be passed inside JSON or YAML blobs:
```bash
stl --arg '{image: "@abe.jpg"}'
# Equivalent:
stl < --username '\@abe'
```
#### Explicit encoding
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`).
```bash
stl --arg @data://file.txt
```
## Workspace Configuration
The CLI supports workspace configuration to avoid repeatedly specifying the project name. When you run a command, the CLI will:
1. Check if a project name is provided via command-line flag
2. If not, look for a `.stainless/workspace.json` file in the current directory or any parent directory
3. Use the project name from the workspace configuration if found
### Initializing a Workspace
You can initialize a workspace configuration with:
```sh
stl workspace init --project your-project-name
```
If you don't provide the `--project` flag, you'll be prompted to enter a project name.
Additionally, when you run a command with a project name flag in an interactive terminal, the CLI will offer to initialize a workspace configuration for you.