| name | image |
| description | Use whenever you need to GENERATE or EDIT a raster image — a mockup graphic, logo, sprite, icon, illustration, banner, product shot, or any "make me a picture of…" request. Always use `beckett image`; never scaffold an image project or call codex/python/SVG yourself. |
image
You can make images. There is one way to do it: the beckett image command. It wraps the
Codex image_gen tool (authed and enabled for you) into a single deterministic call that saves
a real file to an exact path and hands you back that path.
What's actually available on this box
Codex is the documented default, but check before assuming it works: if the codex binary
isn't on PATH, beckett image now falls back automatically to fal (FAL_KEY is what makes
that fallback possible) and says so on stderr — it doesn't hard-fail on a missing default. OpenRouter
is a third option but only works if OPENROUTER_API_KEY/OPENROUTER_KEY is set in ~/.beckett/.env;
don't add that key yourself, just be aware --model openrouter/... will error cleanly if it's absent.
Per-lane flag support:
| Lane | --size | --ref | --transparent |
|---|
Codex (default, when codex is on PATH) | 1024x1024 / 1536x1024 / 1024x1536 / auto | yes (edit mode) | yes |
fal (--model fal-ai/..., or the auto-fallback) | any WIDTHxHEIGHT; mapped to the model's own dialect (image_size pixels, or aspect_ratio like 9:16 for models such as fal-ai/flux-pro/v1.1-ultra/kontext) — a size that can't be expressed for the chosen model is a loud error, never a silent substitution | yes — uploads the file to fal's storage and routes to a model that accepts it (fal-ai/flux-pro/kontext by default if the one you picked doesn't take an image input) | no |
OpenRouter (--model openrouter/...) | 1024x1024 / 1536x1024 / 1024x1536 / auto | no | no |
The one rule
Never improvise image generation. Do NOT create a project (you once made ~/projects/imagegen
instead of just generating), do NOT call codex directly, do NOT reach for python/PIL/SVG/HTML/CSS
to fake a raster image. If the user wants a photo, logo, sprite, icon, illustration, banner, or
product image → beckett image. (If they want a vector/UI asset that should match existing
repo SVGs, edit those directly instead — that's the one case where image gen is the wrong tool.)
Usage
beckett image "<description>" [--out <path>] [--size <s>] [--ref <file[,file]>] [--transparent] [--model <m>]
| Flag | Meaning |
|---|
| (positional) | The image description. Be concrete: subject, style, colors, composition. |
--out <path> | Where to save. Default: ~/.beckett/images/<ts>-<slug>.png. |
--size <s> | 1024x1024 (default), 1536x1024 (landscape), 1024x1536 (portrait), or auto. |
--ref <file[,file]> | Reference image(s) to edit / build on (comma-separated). Turns it into an edit. |
--transparent | Produce a real transparent (alpha) PNG. |
--model <m> | Optional Codex driver model override (rarely needed). |
Returns JSON: { path, bytes, size, prompt, edited, relocated }. path is the absolute file —
that's what you hand off or deploy. (relocated:true just means the wrapper moved the file from
Codex's default dir to your --out; nothing to act on.)
How to write the description
The quality is in the prompt. Give it: the subject, the style ("flat vector", "photoreal",
"pixel-art sprite", "3D render"), palette, background, and any text verbatim in quotes. One
clear paragraph beats a vague line. Example:
beckett image "flat-design app icon: a friendly robot mascot head, rounded squircle, mint-green
background, soft drop shadow, no text" --size 1024x1024 --transparent --out ~/.beckett/images/beckett-icon.png
The usual flow
- Generate →
beckett image "…" --out <path>. Grab path from the JSON.
- Deliver it. A generated image is an artifact like any other:
- To show it in Discord, attach the file:
beckett discord reply --channel <id> --file <path> "here's the mockup"
(the reply command takes --file; see your tool map). Don't just describe it — send it.
- To put it on the web,
beckett deploy a page that references it, or host it (see [[deploy]]).
- Iterate by editing: pass the result back with
--ref <path> and a tweak
("same but warmer palette and a darker background").
This is exactly the muscle for the proactive move (see [[proactive]]) — "saw yall debating the
logo, threw a few options together" — and for delivering visual work ([[deliver]]).
When it errors
- "codex produced no image" — the model didn't save a file. Re-run with a more concrete
description; if it persists, say so plainly rather than faking an image.
- "codex not found ... falling back to fal" — not an error, just a stderr note: the default
renderer wasn't on
PATH so it used fal instead. The image still generated; nothing to do.
- "reference image not found" — the
--ref path is wrong; check it.
- "takes an aspect_ratio, not raw pixels" (fal lane) — the model you picked can't express the
exact
--size you asked for. Pick one of the listed ratios, pass --size auto, or switch to a
model with free-form image_size like fal-ai/flux/dev.
- It can take ~30–60s (it's one generation turn). That's normal; the typing indicator covers it.
