[images] simplify image generation and add inline previews

[saioai]

Draft for review

This is a reviewable snapshot of the image UX work so far, including the saved inline-image baseline and the subsequent onboarding, help, model discovery, naming, and streaming work. It is a draft for feedback, not a release-ready claim of universal terminal support.

What changes for a user

Area	Behavior in this draft
Getting started	Running openai shows a short starting guide; help setup explains credentials, short image help gives a runnable example, and help --all preserves the full flag reference.
Defaults and settings	Ordinary interactive generation uses gpt-image-2.5-sunburst, one PNG, and automatic size/quality/background/moderation. Plain-language guides explain the exact flags and values, including counts from 1 to 10.
Output and downloading	Ordinary interactive generation saves automatically in ~/Downloads/gpt-images/, prints saved paths, and derives filenames from the prompt. Existing files are retained. Explicit API formats and scripting paths remain available.
Model discovery	images models checks a maintained list of exact image model IDs with bounded per-model requests; --offline needs no key. It keeps partial results on timeouts and distinguishes visibility from generation permission.
Previews	Native iTerm2/Kitty/Ghostty previews, text fallbacks, local-file preview, external-viewer support, and remembered automatic-preview preferences.
Apple Terminal experiment	Generated color fonts display image strips while retaining the selected profile, size, and intended text appearance. Setup targets the current tab rather than creating a preset profile.
Progress and errors	Optional partial-image previews while generating, temporary-file cleanup, final-image saving, and concise image error messages with a next step.

--model was already optional; this changes the default in the saving workflow rather than introducing optional model selection. Readable final output and automatic downloads apply to generation; existing editing and variation commands retain their API-output behavior.

Start the code review here

• Implementation map and flow diagrams: folders, request flow, font-rendering flow, storage, and review order.
• User guide: commands, defaults, script compatibility, and recovery.
• cmd/openai/main.go → pkg/cmd/image.go → pkg/cmd/image_output.go → internal/imageoutput/ for the main generation path.
• pkg/cmd/image_stream.go for progress events; help.go, image_help.go, image_options.go, and image_models.go for the user-facing guides.
• pkg/cmd/image_inline_preserved.go, internal/imagefont/, internal/imagefontmac/, and internal/imagegallery/ for the Apple Terminal experiment.

The generated image handler uses small integration hooks into handwritten helpers. The dependency addition is golang.org/x/image v0.44.0. This snapshot contains source, tests, and docs; local executables, generated fonts, preview caches, user images, credentials, and private workspace notes are excluded.

Validation

• Passed all eight image helper packages: imagefont, imagefontmac, imagegallery, imageoutput, imagepreview, imageopen, imageprefs, and imagemodels.
• Passed focused cmd/openai and pkg/cmd tests with -run '^Test(Main|Help|Image[A-Z]|ImagesGenerate(Output|FriendlyStream)|ReportImagePreview)' -count=1.
• Passed go mod verify, git diff --check, and builds for macOS arm64, Windows amd64, and Linux amd64.
• Passed the custom-code check using main's trusted scripts and policy: 588 remaining custom lines against the 1,000-line budget (412 lines of headroom). Candidate: 2f06e498edb324b0ba5f7d66e319e91e866b318b; policy base: 1d4e76cb3cbed9992fc6a8b73e50249d2033e575. This counts customization of generated files, not the total size of this PR.
• Tests used synthetic data and local HTTP servers. Terminal automation tests use mocks; additional macOS tests read installed fonts through CoreText. No live API request was made during these pre-PR checks.
• An initial broader test selector included three existing generated API tests that require the separate mock server on port 4010. Those failed because that server was absent; the focused checks above passed. The full mock-server suite was not run in this preparation.
• Prior manual development testing exercised Apple Terminal profiles and actual generation/progress output. This does not establish support for every font, profile, terminal, or platform.

Areas for mentor / maintainer feedback

• Scope and architecture of the Apple Terminal approach, including copying installed font data, font compatibility, cache growth, and recovery. Font registration lasts for the macOS login session; font selection targets one tab. Original installed font files are not edited.
• Native rendering on Windows and other terminal apps; cross-compilation only verifies that the code builds.
• Apple Terminal resizing, custom spacing, unsupported font settings, and old scrollback. Missing selected font variants require selecting the original font before repair. Cache reset does not delete finished images.
• Model default/catalog maintenance and the boundary between beginner help and the complete API reference.
• Generated-code integration and SDK CODEOWNER review before shipping. This draft does not change workflows, generation metadata, the custom-code budget policy, or release settings.

Try the snapshot

git fetch origin codex/images-save
git switch --track origin/codex/images-save
go build -o openai ./cmd/openai
./openai
./openai images generate --help
./openai images options
./openai images models --offline

The commands above need no API key and generate no images. ./openai help setup explains how to configure a key before making a generation request.

[github-actions]

Castiron custom code

Mixed files: 5 → 6

1 newly customized · 0 customizations removed · 0 existing customizations changed · 0 generated baselines changed

Compared 25664bffc86a → 2f06e498edb3. Generated baselines verified.

File	Result	Current custom patch
pkg/cmd/image.go	Newly customized	+9 / −8

5 existing customizations unchanged

• pkg/cmd/adminorganizationcertificate.go
• pkg/cmd/cmd.go
• scripts/castiron/README.md
• scripts/castiron/custom_code_report.py
• scripts/castiron/test_custom_code_report.py

A changed generated baseline means this report cannot reliably identify which handwritten lines changed.

Inspect the custom-code diff

Download the exact patch produced by this run (requires repository access):

gh run download 35397157585 --repo openai/openai-cli \
  --name castiron-custom-code-35397157585-1 --dir /tmp/castiron-custom-code-35397157585-1
git apply --stat /tmp/castiron-custom-code-35397157585-1/custom-code.patch
cat /tmp/castiron-custom-code-35397157585-1/custom-code.patch

Or reproduce it from an SDK checkout containing the vendored reporter:

git fetch --no-tags origin 1d4e76cb3cbed9992fc6a8b73e50249d2033e575 2f06e498edb324b0ba5f7d66e319e91e866b318b
python3 scripts/castiron/custom_code_report.py report \
  --base 1d4e76cb3cbed9992fc6a8b73e50249d2033e575 \
  --head 2f06e498edb324b0ba5f7d66e319e91e866b318b --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-2f06e498edb3
cat /tmp/castiron-custom-code-2f06e498edb3/custom-code.patch

This is the current full custom patch for mixed files, not an attribution of only the handwritten lines changed by this PR.

Full report and patch