# openai-cli
Adopt this skill: https://proskills.md/skills/other/openai-openai-cli-skills-openai-cli
Page: https://proskills.md/skills/other/openai-openai-cli-skills-openai-cli
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.
## File: skills/openai-cli/SKILL.md
size: 1932
sha: 2f8d3b439e4c168dbc05e49d1f9f7faf6f43127e
upstream: https://github.com/openai/openai-cli/blob/main/skills/openai-cli/SKILL.md
```text
---
name: openai-cli
description: Use the OpenAI API from a shell to upload files, run batches, transcribe audio, save generated images, or export API data. Use for one-off API operations and shell workflows.
---
# OpenAI CLI
Check `openai --version`. Older Python SDK installations can provide a different `openai` executable.
Search offline with a few keywords, such as `openai explore transcribe audio`. Search returns text.
Read the matching command's help before choosing an operation. Check whether it uploads data, starts remote work, or writes files.
## Work with a batch request file
Choose the upload purpose from the user's intended use. If that use is unclear, ask before uploading.
- **Upload for later.** `openai files upload requests.jsonl --purpose batch --format json` returns file metadata. Read its `id` and stop after upload.
- **Submit now.** `openai batches submit requests.jsonl` uploads the file and creates a batch. Add `--wait --output-dir ./results` when the user wants the result files.
- **Resume.** For an existing batch, use `openai batches wait BATCH_ID --output-dir ./results`.
If an upload might have succeeded, check `openai files list` in the same project before retrying.
If batch creation might have succeeded, check `openai batches list`. Reuse confirmed IDs to avoid duplicate uploads or submissions.
## Choose output for the next step
For API metadata, request `--format json` explicitly. Use `--format jsonl` for list records. Piping the default output still produces readable text.
For an image file, use the command's save options. Requesting JSON returns the API payload and bypasses automatic image saving.
Check the process exit status before consuming redirected output. A failed stream or later page can leave partial data.
Use the workload's configured credentials. For untrusted JSON or YAML on stdin, set `OPENAI_UNTRUSTED_STDIN=1` to prevent file reads from that input.
```
## File: README.md
upstream: https://github.com/openai/openai-cli/blob/main/README.md
````text
> Looking for the coding agent? Use [Codex CLI](https://developers.openai.com/codex/cli).
## Installation
Choose your operating system. Each setup installs all CLI commands and turns on automatic updates for normal interactive use.
[macOS](#macos) · [Linux](#linux) · [Windows](#windows) · [When updates run](docs/automatic-updates.md#eligible-invocations)
### macOS
Using Homebrew and zsh, paste both lines together in Terminal. Use the same command for an older Homebrew installation.
```zsh
brew update && brew install --cask openai/tools/openai &&
source "$(brew --prefix)/bin/openai-enable-updates.zsh"
```
[Other shells and Homebrew troubleshooting](docs/installation.md#installing-with-homebrew) · [Install without Homebrew](docs/installation.md#installing-a-prebuilt-binary)
### Linux
On Debian, Ubuntu, or Fedora, [download `openai.sh`](https://github.com/openai/openai-cli/releases/download/v1.51.3/openai.sh).
Open Bash or zsh in the download folder. Paste both lines together.
```sh
echo '3b94b2ac8e73bd16f3803ceea1ba5c08b1c80a3c9b27f75c5b8a9d4d76ff7e00 openai.sh' |
sha256sum -c - && source ./openai.sh
```
Enter your password if sudo asks. [Install over SSH](docs/installation.md#install-over-ssh) · [Other Linux distributions](docs/installation.md#installing-a-prebuilt-binary)
### Windows
1. Open the [Windows installer](scripts/install-windows-release.ps1).
2. Select **Copy raw file**.
3. Paste it into PowerShell without administrator privileges.
The installer downloads the matching ZIP and makes `openai` available in this terminal. [Install with File Explorer](docs/installation.md#windows)
## Explore commands
Run `openai explore` to search for commands in your own words.
For example, to check a prompt's length without an API key, search for `count tokens offline`.
Highlight the command you want and press **Enter** to bring it back to your terminal.
## Authentication
When you're ready to make an API request, run the setup guide for your shell.
```sh
openai help setup
```
For scripts, supply `OPENAI_API_KEY` through your environment or secret manager. [Create an API key](https://platform.openai.com/settings/organization/api-keys)
## Things to try
### Send a request
```sh
openai responses create --model gpt-5.5 --input "Say this is a test"
```
### Generate an image and save it locally
```sh
openai images generate --prompt "A tiny orange robot watering a houseplant"
```
Images are saved to `~/Downloads/gpt-images/`, and the command prints their paths.
Use `--output-dir` for an existing destination directory or `--name` for a filename.
Supported terminals can preview the result. See the [image guide](docs/image-generation-saving.md)
for editing, model selection, and preview settings.
### Upload a file and retrieve it later
```sh
openai files upload report.txt --purpose user_data
openai files get file-example
openai files download file-example --output downloaded-report.txt
```
Use your own local file and replace `file-example` with the ID returned by the upload.
See [working with files](docs/files.md) for more examples.
### Run requests in a batch
Submit a JSONL request file, then wait for the batch and download its results:
```sh
openai files upload requests.jsonl --purpose batch
openai batches create --input-file-id file-example --endpoint /v1/responses --completion-window 24h
openai batches wait batch_example --output-dir ./results
```
Replace the file and batch IDs with the returned IDs. The [batch guide](docs/batches.md)
includes a sample `requests.jsonl` and explains result files and failed requests.
### Export API data for a script
```sh
openai models list --format jsonl | jq '.id'
openai files list --format json > files.json
```
Choose `--format json` for a JSON document or `--format jsonl` for records.
The default output is readable text, **even in pipes**. The first example uses
[jq](https://jqlang.org/).
## Usage
Commands follow the API's resources:
```sh
openai [subresource...] [flags...]
```
Browse commands and options with help. Help needs no API key or network connection.
```sh
openai --help
openai images generate --help
openai admin organization --help
```
`openai help COMMAND` and `openai COMMAND --help` show the same page.
Command groups list their available commands. Each action shows its usage, required inputs, and relevant flags.
When an action has an example, help shows it before the flag descriptions.
To read about one flag, append it after `-h`, as in `openai responses create -h --stream`.
For every flag's description, use `openai help --all responses create`.
Existing colon-separated commands, such as `openai admin:organization:usage completions`,
also work.
### Admin requests
Admin endpoints use `OPENAI_ADMIN_KEY`, a separate
[admin API key](https://platform.openai.com/settings/organization/admin-keys).
For example, retrieve one day of organization usage:
```sh
openai admin organization usage completions --start-time 1735689600 --end-time 1735776000 --bucket-width 1d
```
### Output and errors
Successful JSON responses display readable text by default. Select a data format
explicitly when parsing results. Use `--transform` to extract fields with
[GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md):
```sh
openai files get file-example --transform filename --raw-output
```
Errors go to stderr as readable summaries. Use `--format-error json` for API error
details, or `--transform-error` to extract error fields. Explicit `--format json`,
`jsonl`, `raw`, and `yaml` also apply to errors unless `--format-error` overrides
them; `--format-error text` restores summaries. API error details and `--debug`
logs can contain sensitive data: sanitize them before sharing.
`--debug` adds per-attempt HTTP timing. Add `--debug-body` for redacted JSON
previews or `--debug-sse --debug-event-timing` for bounded stream diagnostics.
See [HTTP debugging](docs/debugging.md) for capture limits and timing boundaries.
Check the command's exit status before using redirected results; a failed request
can leave an incomplete output file. See [reading command results](docs/readable-output.md)
for list formats, streaming, binary downloads, and error behavior.
### File input
Binary uploads take a plain path. JSON input flags can read a value from a local
file with `@path`:
```sh
openai files upload report.txt --purpose user_data
openai responses create --model gpt-5.5 --input @prompt.txt
```
For a complete request, `responses create` and `chat completions create` accept `--request-file request.json`.
Use `--request-file -` to wait for a pipeline, including delayed producers.
Run `openai help piping` for tokenizer, upload, and script examples.
Use `OPENAI_UNTRUSTED_STDIN=1` when piping JSON or YAML from an untrusted source
so input cannot cause local file reads. In that mode, provide upload paths
explicitly as flags. See [file arguments and encoding](docs/cli-reference.md#passing-files-as-arguments)
for escaping literal `@` values, JSON/YAML input, and text or base64 encoding.
### Shell shortcuts
Set up [shell completion](docs/shell-completion.md) to complete commands and file
paths. [Command insertion](docs/command-insertion.md) lets you search examples
with Ctrl+X, then Tab and insert them without running them.
The first eligible interactive run saves image-picker Tab shortcuts for future
````