An agent-friendly CLI for OpenAI image generation, editing, Responses API image conversations, and reusable character references.

Requires Node.js 22.18 or newer, Bun, and Git.

curl -fsSL https://raw.githubusercontent.com/R44VC0RP/imgen/main/install.sh | sh

The installer places the application in ~/.local/share/imgen and links imgen into ~/.local/bin. It does not touch saved credentials, characters, or jobs when reinstalled.

Then save an OpenAI API key using hidden terminal input:

imgen login

OPENAI_API_KEY can be used instead and always takes precedence over the saved key.

Generate a standalone image with the direct Images API (defaults to gpt-image-2.5-sunburst; override with --model):

imgen generate \
  "An isolated cobalt ceramic flower, no backdrop" \
  --out flower.png --quality high --background transparent --wait

Edit one or more local reference images:

imgen edit \
  "Change only the petals to sage green" \
  --image flower.png --out flower-green.png --quality high --wait

Inputs can include up to 16 PNG, JPEG, or WebP files. Use --mask mask.png for guided inpainting.

Transparent generation	Reference edit

respond uses gpt-5.6 with the gpt-image-2.5-sunburst tool by default:

imgen respond \
  "Create two explorers beside a red seaplane" \
  --out explorers.png --wait --json

The JSON result includes a response_id. Continue the image conversation with it:

imgen respond \
  "Keep the same explorers, but move them into a snowy hangar" \
  --previous-response resp_123 \
  --out hangar.png --wait

Use --model to choose the reasoning model, --image-model to choose the image tool model, and --action auto|generate|edit to control the image action.

Generate or choose a clear reference image for each character, then save it:

imgen character add alan \
  --image alan.png \
  --description "Tall, wavy black hair, amber glasses, teal jacket"

imgen character add ryan \
  --image ryan.png \
  --description "Curly auburn hair, mustache, blue glasses, mustard overshirt"

Mention their handles in any new respond request:

imgen respond \
  "Have @ryan and @alan cook pancakes in a cozy cabin kitchen" \
  --out breakfast.png --wait

This is a fresh request—it does not need --previous-response. imgen resolves each @handle, snapshots its saved references into the job, labels them for the model, and attaches them as high-detail image inputs. Handles are case-insensitive.

imgen character list
imgen character show alan
imgen character remove alan

Multiple clean angles can improve consistency:

imgen character add alan \
  --image alan-front.png \
  --image alan-side.png \
  --image alan-full-body.png

@alan reference	@ryan reference

Fresh request: cooking pancakes	Fresh request: rowing at sunrise

Character references guide identity; generative output will still vary between images.

imgen keeps configuration separate from job state and generated output.

Credential, character, and job files are created with private permissions. imgen login stores the key in credentials.json with mode 600; the CLI never accepts a key as a command-line argument.

Environment overrides:

Generation starts as a detached local job unless --wait is supplied:

imgen generate "A quiet alpine lake" --out lake.png --json
imgen status JOB_ID --watch --json

Jobs survive terminal exit but not a reboot or forced worker termination. imgen does not automatically retry failed requests because a disconnected or timed-out request may still incur API charges. Existing output files are never overwritten.

--size WIDTHxHEIGHT|auto
--quality low|medium|high|xhigh|max|auto
--background transparent|opaque|auto
--output-format png|webp|jpeg
--output-compression 0..100
--moderation auto|low
--timeout SECONDS
--wait
--json

Run imgen --help for the complete command reference.

git clone https://github.com/R44VC0RP/imgen.git
cd imgen
bun install
bun run typecheck
bun run build
bun link

The CLI source is src/imgen.ts; the installed executable is built to dist/imgen.js.