1# OpenAI CLI
2
3The official CLI for the [OpenAI REST API](https://platform.openai.com/docs).
4
5<!-- x-release-please-start-version -->
6
7## Installation
8
9### Installing with Homebrew
10
11```sh
12brew install openai/tools/openai
13```
14
15### Installing with Go
16
17To test or install the CLI locally, you need [Go](https://go.dev/doc/install) version 1.25 or later installed.
18
19```sh
20go install 'github.com/openai/openai-cli/cmd/openai@latest'
21```
22
23Once you have run `go install`, the binary is placed in your Go bin directory:
24
25- **Default location**: `$HOME/go/bin` (or `$GOPATH/bin` if GOPATH is set)
26- **Check your path**: Run `go env GOPATH` to see the base directory
27
28If commands aren't found after installation, add the Go bin directory to your PATH:
29
30```sh
31# Add to your shell profile (.zshrc, .bashrc, etc.)
32export PATH="$PATH:$(go env GOPATH)/bin"
33```
34
35<!-- x-release-please-end -->
36
37### Running Locally
38
39After cloning the git repository for this project, you can use the
40`scripts/run` script to run the tool locally:
41
42```sh
43./scripts/run args...
44```
45
46## Usage
47
48The CLI follows a resource-based command structure:
49
50```sh
51openai [resource] <command> [flags...]
52```
53
54Standard API endpoints require an [API key](https://platform.openai.com/settings/organization/api-keys):
55
56```sh
57export OPENAI_API_KEY="sk-..."
58
59openai responses create \
60 --input "Say this is a test" \
61 --model gpt-5.5
62```
63
64Admin endpoints require an [admin API key](https://platform.openai.com/settings/organization/admin-keys):
65
66```sh
67export OPENAI_ADMIN_KEY="sk-admin-..."
68
69openai admin:organization:usage completions \
70 --start-time 1735689600 \
71 --end-time 1735776000 \
72 --bucket-width 1d
73```
74
75For details about specific commands, use the `--help` flag.
76
77### Environment variables
78
79| Environment variable | Required | Default value |
80| ----------------------- | -------- | ------------- |
81| `OPENAI_API_KEY` | no | `null` |
82| `OPENAI_ADMIN_KEY` | no | `null` |
83| `OPENAI_ORG_ID` | no | `null` |
84| `OPENAI_PROJECT_ID` | no | `null` |
85| `OPENAI_WEBHOOK_SECRET` | no | `null` |
86
87### Global flags
88
89- `--api-key` (can also be set with `OPENAI_API_KEY` env var)
90- `--admin-api-key` (can also be set with `OPENAI_ADMIN_KEY` env var)
91- `--organization` (can also be set with `OPENAI_ORG_ID` env var)
92- `--project` (can also be set with `OPENAI_PROJECT_ID` env var)
93- `--webhook-secret` (can also be set with `OPENAI_WEBHOOK_SECRET` env var)
94- `--help` - Show command line usage
95- `--debug` - Enable debug logging. This includes HTTP request/response details and bodies; do not share debug logs if they may contain sensitive payloads.
96- `--version`, `-v` - Show the CLI version
97- `--base-url` - Use a custom API backend URL
98- `--format` - Change the output format (`auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml`)
99- `--format-error` - Change the output format for errors (`auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml`)
100- `--transform` - Transform the data output using [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)
101- `--transform-error` - Transform the error output using [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)
102
103### Passing files as arguments
104
105To pass files to your API, you can use the `@myfile.ext` syntax:
106
107```bash
108openai <command> --arg @abe.jpg
109```
110
111Files can also be passed inside JSON or YAML blobs:
112
113```bash
114openai <command> --arg '{image: "@abe.jpg"}'
115# Equivalent:
116openai <command> <<YAML
117arg:
118 image: "@abe.jpg"
119YAML
120```
121
122If you need to pass a string literal that begins with an `@` sign, you can
123escape the `@` sign to avoid accidentally passing a file.
124
125```bash
126openai <command> --username '\@abe'
127```
128
129#### Explicit encoding
130
131For JSON endpoints, the CLI tool does filetype sniffing to determine whether the
132file contents should be sent as a string literal (for plain text files) or as a
133base64-encoded string literal (for binary files). If you need to explicitly send
134the file as either plain text or base64-encoded data, you can use
135`@file://myfile.txt` (for string encoding) or `@data://myfile.dat` (for
136base64-encoding). Note that absolute paths will begin with `@file://` or
137`@data://`, followed by a third `/` (for example, `@file:///tmp/file.txt`).
138
139```bash
140openai <command> --arg @data://file.txt
141```
142
143## Linking different Go SDK versions
144
145You can link the CLI against a different version of the OpenAI Go SDK
146for development purposes using the `./scripts/link` script.
147
148To link to a specific version from a repository (version can be a branch,
149git tag, or commit hash):
150
151```bash
152./scripts/link github.com/org/repo@version
153```
154
155To link to a local copy of the SDK:
156
157```bash
158./scripts/link ../path/to/openai-go
159```
160
161If you run the link script without any arguments, it will default to `../openai-go`.
162
163## License
164
165Copyright 2026 OpenAI
166
167This project is licensed under the [Apache License 2.0](LICENSE).
