openai-cli
Official OpenAI CLI for interacting with the OpenAI REST API from the command line
How do I install this agent skill?
npx skills add https://github.com/reason-machines/devtools-skills --skill openai-cliIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides instructions for using the OpenAI CLI. While it points to official sources, it contains surfaces for indirect prompt injection via file reading and piping, and it documents a practice for passing API keys that could lead to credential exposure in shell history.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/devtools-skills/openai-cli">View openai-cli on skillZs</a>