openai-cli

OpenAI CLI

Skill by ara.so — Devtools Skills collection.

The official CLI for the OpenAI REST API. Provides a command-line interface to interact with OpenAI's API endpoints including chat completions, embeddings, fine-tuning, and admin operations.

Installation

Homebrew (macOS/Linux)

brew install openai/tools/openai

Go Install

go install 'github.com/openai/openai-cli/cmd/openai@latest'

Ensure Go bin is in your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Local Development

Clone the repository and run locally:

git clone https://github.com/openai/openai-cli.git
cd openai-cli
./scripts/run args...

Configuration

Set up your API credentials using environment variables:

export OPENAI_API_KEY="sk-..."
export OPENAI_ADMIN_KEY="sk-admin-..."  # For admin endpoints
export OPENAI_ORG_ID="org-..."          # Optional
export OPENAI_PROJECT_ID="proj_..."     # Optional

Or use flags on each command:

openai --api-key sk-... responses create --input "Hello"

Environment Variables

Variable	Purpose	Required
OPENAI_API_KEY	Standard API authentication	For standard endpoints
OPENAI_ADMIN_KEY	Admin API authentication	For admin endpoints
OPENAI_ORG_ID	Organization identifier	No
OPENAI_PROJECT_ID	Project identifier	No
OPENAI_WEBHOOK_SECRET	Webhook verification	No

Command Structure

openai [resource] <command> [flags...]

Key Commands

Chat Completions

Create a chat completion:

openai responses create \
  --input "Explain quantum computing in simple terms" \
  --model gpt-4

Stream responses:

openai responses create \
  --input "Write a poem about coding" \
  --model gpt-4 \
  --stream

With system message and temperature:

openai responses create \
  --input "What is recursion?" \
  --model gpt-4 \
  --system "You are a computer science teacher" \
  --temperature 0.7

File Operations

Upload a file:

openai files create \
  --file @training_data.jsonl \
  --purpose fine-tune

List files:

openai files list

Retrieve file content:

openai files retrieve file-abc123

Delete a file:

openai files delete file-abc123

Embeddings

Generate embeddings:

openai embeddings create \
  --input "The quick brown fox" \
  --model text-embedding-3-small

Multiple inputs:

openai embeddings create \
  --input "First text" \
  --input "Second text" \
  --model text-embedding-3-large

Fine-tuning

Create a fine-tuning job:

openai fine-tuning jobs create \
  --training-file file-abc123 \
  --model gpt-3.5-turbo

List fine-tuning jobs:

openai fine-tuning jobs list

Check job status:

openai fine-tuning jobs retrieve ftjob-abc123

Cancel a job:

openai fine-tuning jobs cancel ftjob-abc123

Admin Operations

Usage statistics:

openai admin:organization:usage completions \
  --start-time 1735689600 \
  --end-time 1735776000 \
  --bucket-width 1d

File Handling

Passing Files as Arguments

Use @ prefix for file paths:

openai responses create --arg @input.txt

Within JSON/YAML:

openai <command> --arg '{image: "@image.jpg"}'

openai <command> <<YAML
arg:
  image: "@abe.jpg"
YAML

Explicit Encoding

Force string encoding:

openai <command> --arg @file://myfile.txt

Force base64 encoding:

openai <command> --arg @data://image.png

Absolute paths:

openai <command> --arg @file:///tmp/file.txt

Escaping @ Signs

To pass a literal @ character:

openai <command> --username '\@username'

Output Formatting

Format Options

Control output format with --format:

# Pretty-printed (default for TTY)
openai responses create --input "Hello" --format pretty

# Raw JSON
openai responses create --input "Hello" --format json

# JSONL (one JSON object per line)
openai responses create --input "Hello" --format jsonl

# YAML
openai responses create --input "Hello" --format yaml

# Raw response body
openai responses create --input "Hello" --format raw

Data Transformation

Use GJSON syntax to extract specific fields:

# Get just the message content
openai responses create \
  --input "Hello" \
  --transform "choices.0.message.content"

# Get multiple fields
openai responses create \
  --input "Hello" \
  --transform "{id: id, content: choices.0.message.content}"

Transform errors:

openai responses create \
  --input "Hello" \
  --format-error json \
  --transform-error "error.message"

Global Flags

--api-key           # API key (or use OPENAI_API_KEY)
--admin-api-key     # Admin key (or use OPENAI_ADMIN_KEY)
--organization      # Org ID (or use OPENAI_ORG_ID)
--project           # Project ID (or use OPENAI_PROJECT_ID)
--base-url          # Custom API endpoint
--debug             # Enable debug logging with HTTP details
--version, -v       # Show CLI version
--help              # Show help for command
--format            # Output format (auto, explore, json, jsonl, pretty, raw, yaml)
--format-error      # Error output format
--transform         # GJSON transform for data output
--transform-error   # GJSON transform for error output

Common Patterns

Interactive Chat Session

while true; do
  read -p "You: " input
  openai responses create \
    --input "$input" \
    --model gpt-4 \
    --format pretty
done

Batch Processing

Process multiple inputs from a file:

while IFS= read -r line; do
  openai responses create \
    --input "$line" \
    --model gpt-3.5-turbo \
    --format json >> results.jsonl
done < inputs.txt

JSON Input

Pass structured data:

openai responses create \
  --input "Translate to French" \
  --model gpt-4 \
  --max-tokens 100 \
  --temperature 0.3

Piping Data

echo "Summarize this text" | openai responses create \
  --input "$(cat)" \
  --model gpt-4

Or:

cat document.txt | openai responses create \
  --input "Summarize: $(cat -)" \
  --model gpt-4

Image Analysis

openai responses create \
  --input '{text: "What is in this image?", image: "@photo.jpg"}' \
  --model gpt-4-vision-preview

Custom Base URL

For Azure or custom endpoints:

openai --base-url https://custom.openai.azure.com/v1 \
  responses create \
  --input "Hello" \
  --model gpt-4

Debugging

Enable debug mode to see full HTTP requests/responses:

openai --debug responses create --input "Test"

Warning: Debug logs include request/response bodies which may contain sensitive data.

Troubleshooting

Command Not Found

Ensure Go bin is in your PATH:

echo $PATH | grep "$(go env GOPATH)/bin"
# If not found:
export PATH="$PATH:$(go env GOPATH)/bin"

Authentication Errors

Verify API key is set:

echo $OPENAI_API_KEY
# Should output: sk-...

Check key validity:

openai responses create --input "test" --model gpt-3.5-turbo

File Not Found Errors

Use absolute paths or verify relative paths:

# Absolute path
openai files create --file @/full/path/to/file.jsonl --purpose fine-tune

# Verify file exists
ls -la @file.jsonl

Rate Limiting

Add delays between requests:

for i in {1..10}; do
  openai responses create --input "Request $i"
  sleep 1
done

Model Not Available

List available models (if endpoint exists):

openai models list

Check model name spelling and access permissions.

Output Not Formatted

Force format explicitly:

openai responses create --input "Hello" --format json

Check if output is being piped (auto-detection may choose raw format):

openai responses create --input "Hello" --format pretty | less

Linking Custom SDK Versions

For development, link against different Go SDK versions:

# Link to specific version
./scripts/link github.com/openai/openai-go@v1.2.3

# Link to local SDK copy
./scripts/link ../openai-go

# Default (../openai-go)
./scripts/link

Version Information

Check CLI version:

openai --version
# or
openai -v

Get help:

openai --help
openai responses --help
openai responses create --help