图像生成与编辑命令行工具

image-gen

Command-line tool for generating and editing images with OpenAI (GPT Image), Google Gemini, and xAI Grok.

Requirements

• Bun >=1.0.0

Quick Start

bun install

Install the published CLI globally:

bun add -g @ebeloded/image-gen

Store API keys securely (use whichever providers you need):

img keys set openai
img keys set gemini
img keys set grok

API Key Management

Store keys in macOS Keychain (or Secret Service on Linux):

img keys set openai
img keys set gemini
img keys set grok

When the key argument is omitted, img prompts securely in a terminal. Pipe it for scripts to keep it out of shell history and process listings:

echo "sk-proj-..." | img keys set openai

View and manage keys:

img keys               # show all key statuses (masked)
img keys get openai    # print raw key value
img keys delete openai # remove a key
img keys migrate       # move legacy plaintext keys into the system keyring

Environment variables (OPENAI_API_KEY, GEMINI_API_KEY/GOOGLE_API_KEY, XAI_API_KEY) override stored credentials and are shown by img keys list without revealing their values.

On a system without a supported keyring, keys set falls back to the private ${XDG_CONFIG_HOME:-~/.config}/image-gen/config.json file (0600). You can request that fallback explicitly with img keys set <provider> --plaintext. Existing plaintext credentials continue to work; img keys migrate copies all of them into the keyring, verifies each readback, and only then removes them from the file. A failed migration rolls back already-written keyring entries and leaves the config unchanged.

A local .image-gen.json in the working directory takes precedence over the user config (for project-level overrides).

Running

Run directly from this repo:

bun run cli.ts --help

After a package install or link, the img and image-gen binaries are on your PATH:

img --help
img --version # or: img -v

The longer image-gen binary is also available as a compatibility alias.

Commands

img openai [options] [prompt]
img gemini [options] [prompt]
img grok   [options] [prompt]
img keys   [command]

image-gen is an equivalent longer binary alias, so image-gen openai ... works the same as img openai ....

Help follows the command hierarchy, so it stays short and relevant:

img --help          # command overview
img openai --help   # OpenAI options and examples
img keys --help     # storage and migration commands
img help gemini     # equivalent help-command form

Command and option typos suggest close matches. Parse errors print help for the command that failed.

CLI Flags (Full Reference)

Common flags (all generation commands):

Permissive CLI input forms:

• --flag value
• --flag=value
• short aliases (-p, -o, -i, -f)
• positional prompt fallback when --prompt/-p is omitted

OpenAI flags (img openai):

OpenAI output file extensions: .png, .jpg, .jpeg, .webp

Gemini flags (img gemini):

Gemini output file extensions: .png

Grok flags (img grok):

Grok output file extensions: .jpg, .jpeg

CLI Examples

Generate with OpenAI:

img openai \
  --prompt "A neon cat in rainy Tokyo, cinematic lighting" \
  --output ./cat.png

Generate with OpenAI by piping prompt from stdin:

cat prompt.txt | img openai --output ./cat.png

Or with stdin redirection:

img openai --output ./cat.png < prompt.txt

Edit with OpenAI:

img openai \
  --prompt "Add snow and keep the cat centered" \
  --output ./cat-snow.png \
  --input ./cat.png

Generate with Gemini:

img gemini \
  --prompt "A ceramic teapot product photo on white background" \
  --output ./teapot.png \
  --aspect-ratio 4:3 \
  --image-size 2K

Edit with Gemini and multiple references:

img gemini \
  --prompt "Combine both references into one consistent illustration" \
  --output ./combined.png \
  --input ./ref-1.png \
  --input ./ref-2.png

JSON Output Behavior

Successful runs print formatted JSON to stdout. Shape:

{
  "success": true,
  "path": "/absolute/path/to/output.png",
  "bytes": 123456,
  "...provider_fields": "..."
}

Provider-specific success fields:

• OpenAI: model, size, quality, input_images_count
• Gemini: model, aspect_ratio, image_size, input_images_count
• Grok: model, aspect_ratio, resolution, quality, input_images_count

Errors and Exit Codes

• Exit 0: Help (--help), version output (--version), or successful generation.
• Exit 1: Argument parsing/validation errors, runtime errors, API/auth errors, file errors.
• Parse/validation errors are written to stderr with command-specific usage.
• Runtime errors are written to stderr as Error: <message>.

Common parse failures include a missing --output, a missing prompt, unknown options (with close-match suggestions), and values outside the choices shown by img <provider> --help.

Troubleshooting

Missing API Key

Each provider command requires its key in the system keyring, legacy config, or an environment variable:

Error: No OpenAI API key found. Run 'img keys set openai' or set OPENAI_API_KEY
Error: No Gemini API key found. Run 'img keys set gemini' or set GEMINI_API_KEY / GOOGLE_API_KEY
Error: No xAI API key found. Run 'img keys set grok' or set XAI_API_KEY

Fix — store the key securely or provide an environment variable:

img keys set openai
img keys set gemini
img keys set grok

Invalid or Unsupported Flags

If you pass a flag not supported by the selected command, the CLI exits with code 1 and prints a command-specific unknown-flag message with a suggestion when a close match exists.

If you pass an unsupported value, the CLI prints the allowed values for that flag.