@versatly/openai-image-cli

OpenAI Image CLI

Comprehensive CLI for OpenAI image generation. Supports GPT Image models (gpt-image-1.5, gpt-image-1, gpt-image-1-mini) and legacy DALL‑E models.

Installation

npm install -g @versatly/openai-image-cli

Authentication

# Via environment variable
export OPENAI_API_KEY=sk-...

# Or via config file
openai-image config set api-key sk-...

Usage

openai-image <command> [options]

Commands

1) generate — Create images from text prompts

openai-image generate "A futuristic city at sunset" [options]

Options:

• -m, --model <model>: gpt-image-1.5 (default), gpt-image-1, gpt-image-1-mini, dall-e-3, dall-e-2
• -s, --size <size>: 1024x1024 (default), 1536x1024, 1024x1536, auto, or DALL‑E sizes
• -q, --quality <quality>: auto (default), high, medium, low (GPT); hd/standard (DALL‑E 3)
• -n, --count <n>: 1–10 (default: 1)
• -f, --format <format>: png (default), jpeg, webp
• -o, --output <path>: Output file/directory (default: ./generated-{timestamp}.png)
• -b, --background <bg>: auto (default), transparent, opaque
• --compression <0-100>: Compression for jpeg/webp (default: 100)
• --moderation <level>: auto (default), low
• --stream: Enable streaming with partial images
• --partial-images <0-3>: Partial images during streaming (default: 0)
• --json: Output JSON response
• --dry-run: Show request without executing

Examples:

# Basic generation
openai-image generate "A cute robot reading a book"

# High quality landscape
openai-image generate "Mountain sunset panorama" -s 1536x1024 -q high

# Multiple images with transparency
openai-image generate "Logo design for coffee shop" -n 4 -b transparent -f png

# Streaming with partials
openai-image generate "Epic fantasy battle scene" --stream --partial-images 2

# Output to a specific file
openai-image generate "Product photo" -o ./product.png

2) edit — Edit existing images

openai-image edit <image> "Edit instructions" [options]

Arguments:

• <image>: Input image path, URL, or file ID

Options:

• -m, --model <model>: gpt-image-1.5 (default), gpt-image-1, dall-e-2
• --mask <path>: Mask image for inpainting (transparent areas get edited)
• --images <paths...>: Additional reference images (up to 16 total for GPT models)
• -s, --size <size>: Output size
• -q, --quality <quality>: Quality level
• -n, --count <n>: Number of variations
• -f, --format <format>: Output format
• -o, --output <path>: Output path
• --stream: Enable streaming

Examples:

# Simple edit
openai-image edit photo.png "Add sunglasses to the person"

# Inpainting with mask
openai-image edit room.png "Add a plant in the corner" --mask mask.png

# Multi-image reference
openai-image edit base.png "Combine these items into a gift basket" --images item1.png item2.png item3.png

3) vary — Create image variations (DALL‑E 2 only)

openai-image vary <image> [options]

Arguments:

• <image>: Input image (PNG, <4MB, square)

Options:

• -n, --count <n>: Number of variations (default: 1)
• -s, --size <size>: 256x256, 512x512, 1024x1024 (default)
• -o, --output <path>: Output path/directory

4) batch — Batch generation from file or stdin

openai-image batch [options]

Options:

• -i, --input <file>: Input file with prompts (one per line, or JSON/JSONL)
• --stdin: Read prompts from stdin
• -m, --model <model>: Model for all generations
• -o, --output-dir <dir>: Output directory (default: ./batch-{timestamp}/)
• --parallel <n>: Concurrent requests (default: 3)
• --delay <ms>: Delay between requests (default: 100)

Examples:

# From file
openai-image batch -i prompts.txt -o ./output/

# From stdin
cat prompts.txt | openai-image batch --stdin

# JSONL with per-prompt options
openai-image batch -i prompts.jsonl

prompts.jsonl format:

{"prompt": "A red car", "size": "1024x1024", "quality": "high"}
{"prompt": "A blue boat", "size": "1536x1024"}

5) config — Manage configuration

openai-image config <command>

Commands:

• set <key> <value>: Set config value
• get <key>: Get config value
• list: List all config
• reset: Reset to defaults
• path: Show config file path

Keys:

• api-key: OpenAI API key
• default-model: Default model (gpt-image-1.5)
• default-size: Default size (1024x1024)
• default-quality: Default quality (auto)
• default-format: Default output format (png)
• output-dir: Default output directory (./)
• save-history: Save history entries (true)

6) models — List available models

openai-image models [options]

Options:

• --json: Output as JSON

7) history — View generation history (local)

openai-image history [options]

Options:

• -n, --limit <n>: Number of entries (default: 20)
• --json: Output as JSON
• --clear: Clear history

Configuration File

Location: ~/.config/openai-image-cli/config.json

{
  "apiKey": "sk-...",
  "defaultModel": "gpt-image-1.5",
  "defaultSize": "1024x1024",
  "defaultQuality": "auto",
  "defaultFormat": "png",
  "outputDir": "./",
  "saveHistory": true
}

Output

Default output (human-readable):

✓ Generated image saved to ./generated-1707500000.png
  Model: gpt-image-1.5
  Size: 1024x1024
  Quality: high
  Tokens: 150 (text: 10, image: 140)

JSON output (generate only):

{
  "success": true,
  "file": "./generated-1707500000.png",
  "model": "gpt-image-1.5",
  "size": "1024x1024",
  "quality": "high",
  "usage": {
    "total_tokens": 150,
    "input_tokens": 50,
    "output_tokens": 100
  },
  "created": 1707500000
}

Error Handling

• Clear error messages with suggestions
• Rate limit detection with retry guidance
• Content policy violation explanations
• Network timeout handling
• Invalid API key detection

License

MIT