0.1.13 — Import images and save artifact copies

English

Bring existing images into a session and save any artifact wherever you need it.

Import images into a session

• imagen session import-image <session> <path> copies a local image into the session as a new artifact. The source file is untouched, and the copy is validated (64 MiB byte cap, Pillow format and pixel checks) before it is published.
• Imported images appear in session show and the TUI artifact strip, and work with transforms, edits, model runs, comparison and save-as.
• imagen asset save <artifact> <path> writes a SHA-256-verified copy to a new path and refuses to replace an existing file.

TUI

• i imports an image; S saves the current artifact as a copy.
• A built-in file picker lists folders first, shows common image formats, navigates with Backspace and accepts a typed path. It does not need a native dialog, so Windows drive and UNC roots behave like POSIX roots.
• Help, the key bar and the : palette list both actions.

Docs

• The English and Simplified Chinese READMEs and the bundled imagen-assets guide (version 1.4.0) document the new commands.

Verification

• Offline suite: 1786 passed, 3 skipped, 4 deselected; ruff, mypy, CLI help/schema JSON and generated documentation checks passed. The extra skip is the optional real x2 upsample model, which is not installed in the isolated check environment.
• Nine GitHub CI jobs passed on Linux, macOS and Windows across Python 3.12, 3.13 and 3.14.
• Import and save-as were run end to end in an isolated workspace: the original bytes stayed identical, the saved copy matched, and a second save to the same path returned conflict.
• No paid provider request, model weight download or real inference was part of this release.

中文

把已有图片导入会话，并把任意产物另存到需要的位置。

把图片导入会话

• imagen session import-image <session> <path> 把本地图片复制进会话成为新产物。原文件不会被修改，复制前会校验大小（上限 64 MiB）以及 Pillow 能识别的格式与像素上限。
• 导入的图片会出现在 session show 和 TUI 产物条中，可用于变换、编辑、模型处理、比较和另存。
• imagen asset save <artifact> <path> 把经过 SHA-256 校验的副本写到新路径，不覆盖已有文件。

TUI

• i 导入图片，S 把当前产物另存副本。
• 内置文件选择器先列目录、只显示常见图片格式，可用 Backspace 返回上一级，也可以直接输入路径。它不依赖系统对话框，Windows 盘符和 UNC 根目录与 POSIX 根目录行为一致。
• 帮助页、底部键栏和 : 命令面板都列出这两个操作。

文档

• 中英文 README 和随包 imagen-assets 指南（1.4.0）已补充新命令。

验证

• 离线回归：1786 passed、3 skipped、4 deselected；ruff、mypy、CLI help/schema JSON 和生成文档检查通过。多出的一项跳过是需要本地 x2 超分权重的可选测试，隔离检查环境未安装该权重。
• Linux、macOS、Windows × Python 3.12、3.13、3.14 的九组 GitHub CI 全部通过。
• 在隔离工作区端到端导入并另存：原图字节不变，副本一致，向同一路径二次另存返回 conflict。
• 本次发布没有发送付费供应商请求、下载模型权重或执行真实推理。

升级 / Upgrade

uv tool upgrade imagen-cli
imagen --version

全新安装并启用 TUI 与 CPU ONNX 模型处理：

uv tool install "imagen-cli[tui,postprocess,ai-onnx]==0.1.13"

0.1.12 — Local processing jobs and model workbench

English

Local outputs and processing jobs

• Transform and model outputs are visible in CLI session history and the TUI, including outputs saved before this release.
• imagen transform and imagen superres run block until completion by default. --wait makes that explicit; --async queues work on an already-running worker. Background jobs support job get, job wait, cancellation and recovery of staged outputs after a crash.
• CLI and TUI progress follows completed pipeline steps or model tiles. --output json returns one result; --output jsonl emits progress events.
• Jobs freeze their input and processing parameters. Cancellation and worker ownership are checked again before publishing an output, and original images are not overwritten.

A dedicated model workbench

• The model page now has a catalog with category filters, an original-image preview, expected output dimensions, and model task, license and source details.
• Backend, tile size, overlap, timeout and foreground/background mode are adjustable. Fixed-input models set their required geometry; switching back restores the editable values.
• Weight download and permission to run a model are separate. Closing the page during a download lets that download finish; it does not start inference.
• CLI, TUI and bundled guides now agree on local-job parameters and output browsing. The bundled imagen and imagen-assets guides are version 1.3.0.

TUI shutdown fixes

• Late progress updates, download callbacks and session polling no longer query controls after their page is removed or while the app is shutting down.
• Regression tests cover removed pages, worker cancellation and partial shutdown where some sibling controls are still attached.

Upgrade

uv tool upgrade imagen-cli
imagen --version

For a fresh install with CPU ONNX model processing:

uv tool install "imagen-cli[tui,postprocess,ai-onnx]==0.1.12"

中文

本地产物与处理任务

• 变换和模型产物重新出现在 CLI 会话历史与 TUI 中，也包括此前保存的本地产物。
• imagen transform 和 imagen superres run 默认等待处理完成，--wait 可显式指定；--async 将任务交给已经运行的 worker。后台任务支持 job get、job wait、取消，以及崩溃后恢复已暂存的产物。
• CLI 与 TUI 按实际完成的管线步骤或模型分块更新进度。--output json 返回一个结果，--output jsonl 输出进度事件流。
• 任务固定输入与处理参数，发布产物前再次检查取消状态和 worker 所有权，不覆盖原图。

独立模型工作台

• 模型页改为带分类筛选的模型列表，显示原图预览、预计输出尺寸，以及模型用途、许可和来源。
• 后端、分块尺寸、重叠、超时和前台／后台模式可以直接调整。固定输入尺寸的模型自动使用规定参数，切回其他模型后恢复可编辑的值。
• 下载权重与运行模型分别确认。下载时关闭页面会让下载继续完成，不会自动开始推理。
• CLI、TUI 与随包指南同步了本地任务参数和产物浏览方式。随包 imagen、imagen-assets 指南版本为 1.3.0。

TUI 关闭修复

• 页面移除或应用开始关闭后，迟到的进度更新、下载回调和会话轮询不再访问已拆除的控件。
• 回归测试覆盖页面移除、worker 取消，以及部分控件仍挂载时的关闭过程。

升级

uv tool upgrade imagen-cli
imagen --version

全新安装并启用 CPU ONNX 模型处理：

uv tool install "imagen-cli[tui,postprocess,ai-onnx]==0.1.12"

Verification / 验证

• Release commit 62078af passed all nine GitHub CI jobs: Linux, macOS and Windows × Python 3.12, 3.13 and 3.14. CI results.

• Local release-tree checks: 1772 passed, 3 skipped, 4 deselected; ruff, mypy, CLI help/schema JSON and generated documentation checks passed.

• The wheel was installed in an isolated environment with TUI and CPU ONNX extras. Shutdown callbacks, blocking local jobs, JSONL progress, output visibility and unchanged original bytes passed their checks.

• Both distribution archives were inspected for private paths and credential-shaped content; none were found. Package metadata validation passed.

• No paid provider request, model weight download or real inference was run for this release.

• 发布提交 62078af 的 九组 GitHub CI 全部通过：Linux、macOS、Windows × Python 3.12、3.13、3.14。CI 结果。

• 本地发布代码树检查：1772 passed、3 skipped、4 deselected；ruff、mypy、CLI help/schema JSON 和生成文档检查通过。

• wheel 在隔离环境中安装了 TUI 和 CPU ONNX extras，关闭回调、阻塞本地任务、JSONL 进度、产物可见性和原图字节不变检查通过。

• 两份发行包检查未发现私有路径或凭据特征内容，包元数据校验通过。

• 本次发布没有发送付费供应商请求、下载模型权重或执行真实推理。

0.1.11 — Model runs get room and time to finish

English

Model runs now have enough memory and time to finish, and a missing runtime says what to install.

Model inference gets room to run

• A 1024 px image at 4x failed inside an ONNX Upsample node with Failed to allocate memory. The worker capped address space at 2 GiB for every pipeline, while inference reserves weights, arenas and float32 feature maps far beyond the pixel buffers. Pipelines with a model step now get 6 GiB; ordinary transforms keep 2 GiB.
• Tiled upscaling writes its output buffer as uint8 instead of float32. An 8192x8192 result drops from 805 MB to 201 MB, with the same pixels.
• The default timeout for a model step rises from 120 s to 900 s. A 4x run on a 1024 px image takes about three minutes on CPU, so the old default failed before the work could finish. --timeout still overrides it.
• Running out of memory now reports "not enough memory for this operation; retry with a smaller tile or a smaller image" instead of the runtime's node name and byte count.

Clearer failures

• A missing ONNX runtime names the command that installs it: imagen superres install --backend cpu --accept. Before, it only mentioned a packaging extra that a uv tool install cannot add.
• ValueError text reaches the terminal as written; other errors keep their class name.

Interface and docs

• The providers panel title is translated; Chinese showed the English word.
• English and Simplified Chinese READMEs were rewritten around one workflow, with 24 current screenshots covering the workspace, plans, providers, processing, model pages and CLI output. Screenshots come from a local workspace with no provider requests, model downloads or inference.
• The repository and package description now say terminal image workbench and name the endpoints that work today.

Verification

• Final offline run: 1723 passed, 2 skipped, 4 deselected. The two skipped tests need a live provider request this release did not authorize, and a Windows ACL check this machine cannot run.
• ruff and mypy pass.
• A 1024x1024 image upscaled to 4096x4096 through the real worker in 3 min 21 s, after failing on the same input before the change.

No paid provider request was sent and no model weights were downloaded for this release.

中文

模型推理现在有足够的内存和时间跑完；缺少运行时会直接告诉你要装什么。

模型推理有运行空间

• 1024 像素的图片做 4 倍放大时，在 ONNX 的 Upsample 节点里报 Failed to allocate memory。worker 给所有管线都设了 2 GiB 地址空间上限，而推理要为权重、arena 和 float32 特征图预留远超像素缓冲的空间。含模型步骤的管线现在放宽到 6 GiB，普通变换仍是 2 GiB。
• 分块放大把输出缓冲从 float32 改成 uint8。8192×8192 的结果从 805 MB 降到 201 MB，像素值不变。
• 模型步骤的默认超时从 120 秒提高到 900 秒。1024 像素的 4 倍放大在 CPU 上大约要三分钟，旧默认等不到完成。--timeout 仍可覆盖。
• 内存不足时提示改为「not enough memory for this operation; retry with a smaller tile or a smaller image」，不再输出运行时的节点名和字节数。

更清楚的报错

• 缺少 ONNX 运行时会给出安装命令：imagen superres install --backend cpu --accept。之前只提到一个 uv tool 安装无法追加的 packaging extra。
• ValueError 的文本原样到达终端；其他异常保留类名。

界面与文档

• 端点面板标题已翻译，中文界面之前显示的是英文。
• 中英文 README 按一条工作流程重写，配 24 张当前截图，覆盖工作区、计划、端点、处理、模型页和 CLI 输出。截图来自本地工作区，没有供应商请求、权重下载或推理。
• 仓库与包描述改为 terminal image workbench，并写明当前可用的端点。

验证

• 最终离线回归：1723 passed、2 skipped、4 deselected。跳过的两项分别需要本次未授权的真实供应商请求，以及本机无法执行的 Windows ACL 检查。
• ruff 与 mypy 通过。
• 1024×1024 通过真实 worker 放大到 4096×4096，耗时 3 分 21 秒；改动前同样的输入会失败。

本次发布没有发送付费供应商请求，也没有下载模型权重。

升级 / Upgrade

uv tool upgrade imagen-cli
imagen --version

0.1.10 — Large-image confirmation and a separate model-processing entry

English

Large images ask before processing, and image processing now has its own entry, separate from model processing.

Large images ask first

• When a request exceeds the default input/output pixel budget or the working-buffer budget, Imagen shows the input and output size, the pixel count, and the memory risk, then asks whether to continue. The default answer is cancel.
• The TUI uses a confirmation dialog; an interactive CLI asks [y/N]; a non-interactive call returns approval_required with a budget digest. Accept the risk explicitly, then repeat the same request with --budget-approval DIGEST.
• The digest covers the source image contents and the processing parameters. Changing either one asks again. The same confirmation now carries through the worker and through artifact save and reopen, so a large result no longer fails at save time on the same default limit.
• Output is saved as a new artifact. Parameter validation, cancel, and worker isolation work as before.
• tiled_upscale keeps one float32 output image and drops the redundant float64 accumulation and weight buffers, which lowers peak memory on large images.

Image processing and model processing are separate

• TUI: t (Transform) opens ordinary image processing. u (Models) opens model restoration and upscaling on its own page. s still manages local weights and runtimes.
• CLI: new imagen superres run ART --model MODEL, separate from imagen transform ART .... Both use the same execution, budget confirmation, and artifact storage path.
• Existing transform --op superres:... scripts keep working.

imagen superres run ART --model film-degrainer
imagen superres run ART --model realesrgan-x4plus --backend cpu
# Over budget without a terminal: the first call returns a digest, then rerun the same request:
imagen superres run ART --model realesrgan-x4plus --budget-approval DIGEST --agent

Verification

• CI 40682673950: Linux/macOS/Windows × Python 3.12/3.13/3.14, all 9 jobs passed, commit 5403e1b0da286809be28966ff58e71f8f8237d31.
• Final offline run: 1715 passed, 2 skipped, 4 deselected. The skipped tests need a live provider request this release did not authorize, and a Windows ACL check this machine cannot run. ruff and mypy (Linux, win32, darwin) passed.
• The wheel and sdist were checked against the source and docs, then installed with the tui,postprocess extras in a clean /tmp environment to verify the version and the new command schema.
• A real CLI run took 2048×2048 to 8192×8192 (67,108,864 pixels) through confirmation, save, and reopen, with the source digest unchanged. Plain scaling exercised that path; no model inference ran.
• Regression tests cover CLI/TUI cancel and confirm, changed parameters or source image, save and reopen, and the split model entry.

The captured CLI run used plain scaling. This release downloaded no weights and sent no paid provider requests.

Upgrade

uv tool upgrade imagen-cli
imagen --version

中文

大图先询问再处理；图像处理与模型处理拆成两个入口。

大图先询问

• 请求超过默认输入/输出像素预算或工作缓冲预算时，Imagen 显示输入输出尺寸、像素量和内存风险，再询问是否继续。默认取消。
• TUI 使用确认对话框；交互式 CLI 询问 [y/N]；非交互调用返回 approval_required 和预算摘要。明确接受风险后，用相同参数加 --budget-approval DIGEST 重跑。
• 摘要绑定原图内容与处理参数，改动任一项都会重新询问。同一次确认现在贯穿 worker 与产物的保存、重开，大图不会再因同一个默认上限卡在保存阶段。
• 输出另存为新产物。参数校验、取消和 worker 隔离照常工作。
• tiled_upscale 只保留一份 float32 输出图，去掉冗余的 float64 累加与权重缓冲，降低大图的内存峰值。

图像处理与模型处理分离

• TUI：t（变换）打开普通图像处理；u（模型）打开独立的模型恢复与超分页；s 仍管理本地权重和运行时。
• CLI：新增 imagen superres run ART --model MODEL，与 imagen transform ART ... 分开，两者共用同一套执行、预算确认和产物保存链路。
• 旧的 transform --op superres:... 脚本继续可用。

imagen superres run ART --model film-degrainer
imagen superres run ART --model realesrgan-x4plus --backend cpu
# 无终端且超预算时，第一次调用返回摘要，然后带上它重跑同一请求：
imagen superres run ART --model realesrgan-x4plus --budget-approval DIGEST --agent

验证

• CI 40682673950：Linux/macOS/Windows × Python 3.12/3.13/3.14，9 项全部通过，对应提交 5403e1b0da286809be28966ff58e71f8f8237d31。
• 最终离线回归：1715 passed、2 skipped、4 deselected。跳过的两项分别需要本次未授权的真实供应商请求，以及本机无法执行的 Windows ACL 检查。ruff 与 mypy（Linux、win32、darwin）通过。
• wheel 与 sdist 已核对源码和文档，随后在干净的 /tmp 环境安装 tui,postprocess extras，验证版本号与新命令 schema。
• 真实 CLI 跑通 2048×2048 → 8192×8192（67,108,864 像素）：确认、保存、重新读取全程完成，原图摘要未变。这一步用普通缩放验证链路，没有执行模型推理。
• 回归测试覆盖 CLI/TUI 的取消与确认、更换参数或原图、保存与重开，以及模型入口拆分。

截图中的 CLI 运行使用普通缩放。本次没有下载权重，也没有发送付费供应商请求。

升级

uv tool upgrade imagen-cli
imagen --version

0.1.9

Release 0.1.9

Provider parameters across CLI, TUI and planning

• A shared provider vocabulary now drives parameter validation, CLI schema and TUI candidates.
• OpenAI Images accepts custom pixel dimensions on the supported GPT Image 2 family, with grid, aspect-ratio, edge and pixel-count validation. Supported 2.5-family quality tiers include xhigh and max.
• Gemini uses --aspect-ratio and --image-size; model-specific tiers are checked before approval and forwarded as generationConfig.imageConfig.
• Unspecified geometry stays omitted. Gemini no longer receives an injected size=1024x1024 from the TUI.
• Unsupported execution routes and locally refused retired model IDs are rejected before approval. This build dispatches only openai/images and gemini/generate_content.

TUI and local model workflow

• Selection-first forms provide known sessions, artifacts, profiles and models with custom input fallbacks.
• A dedicated local-model panel shows download state and supports model-based restoration as well as upscaling.
• Selecting a missing local model offers a source/license confirmation before downloading; the run starts only when requested again.
• Shared modal behavior and compact controls improve keyboard and mouse interaction.

Bundled agent skills

imagen and imagen-batch are now 1.2.0. Their guides distinguish provider geometry, model-specific limits, mixed-batch fields and individual offline previews. Existing approval, unknown-outcome and no-overwrite boundaries remain in place.

Cross-platform checks

Release commit 320472f passed all nine CI jobs: Linux, macOS and Windows with Python 3.12, 3.13 and 3.14. A Unix-only PTY regression test was replaced with a portable terminal-stream contract test; production rendering was unchanged.

Install or upgrade

uv tool install "imagen-cli[tui,postprocess]==0.1.9"
# Existing uv installation:
uv tool upgrade imagen-cli
imagen --version

Verification limits

Provider changes were checked with offline contracts and captured request bodies, not paid generation calls. A valid plan does not prove remote model availability or the actual output dimensions. Local-model downloads and inference dependency installation still require separate explicit approval. No model weights are included in this release.

0.1.8

Tighter TUI controls

Buttons, inputs and selects are a single borderless row now: terminal rows belong to the
image, not the chrome. Focus shows as an accent fill, forms no longer leave a blank row
between a label and its field, and the single-line contract is asserted at the 80×24
regression size. Two Textual details surfaced on the way: SelectCurrent draws its own
tall border (a stray bar inside a one-row Select), and padding on Select swallows the
mouse click that opens its overlay.

One install command

runtime install is gone. imagen superres install installs the inference runtime alone
when --model is omitted, or the runtime plus the named weights when it is given. The TUI
palette and forms are generated from the command registry, so CLI and TUI expose exactly
one surface.

imagen superres install --backend cpu                              # preview, runtime only
imagen superres install --backend cpu --accept                     # install runtime only
imagen superres install --model realesr-animevideov3 --accept      # runtime + weights

Human output through Rich

Human summaries are printed with a real Rich Console instead of hand-written ANSI
strings written to stdout. Color no longer depends on TERM, which Windows never sets,
and Rich handles Windows consoles and terminal width on its own. Pipes, NO_COLOR and
TERM=dumb keep the previous plain-text layout, and the non-terminal contract is pinned
by tests.

Verification

• ruff check . and mypy src (111 files) clean; full pytest suite green.
• The new terminal path is covered by a pseudo-terminal test (styling with TERM unset)
  and by piped-output tests (no escape codes), measured against Rich documentation.
• Windows privilege handling from the preceding commit was verified by the maintainer on a
  Windows machine; the rewritten human-output path here has not been run on Windows by the
  author.

v0.1.7

Imagen CLI 0.1.7

Changes

• New runtime install command previews or installs ONNX runtime packages (cpu, cuda, openvino) into the running virtual environment; system Python and conflicting backends are refused, and drivers are never installed.
• Same-size model restoration now available through superres: film-degrainer (denoise) and dejpg-srformer-light (JPEG artifact cleanup). Neither enlarges the image.
• Model catalog exposes a task field so callers can distinguish upscale, denoise, and dejpeg weights.
• Non-finite model output is rejected instead of being written as a corrupt image; x2 models pad odd input dimensions correctly.
• TUI command palette exposes runtime installation; the restoration picker lists the new models.
• README and bundled imagen-assets skill updated.

v0.1.6

Imagen CLI 0.1.6

OpenAI-compatible Images remains the primary setup; Gemini native is now an optional configured protocol.

Changes

• Selection-first TUI forms for protocol, official/custom endpoint, model catalog path, saved profile, and model, with manual fallbacks and preservation of custom values.
• CLI profile set --models-path, same-origin catalog routing, legacy-profile compatibility, and catalog invalidation on endpoint/protocol changes.
• Gemini native custom HTTPS gateways, nano-banana-2 aliases, generation/editing, and private native-context continuation.
• Gemini catalog parsing falls back to OpenAI-style data only when the native models field is absent; no alternate-path requests or automatic creation retries.
• English and Chinese README setup examples, with OpenAI first and Gemini-specific limits documented.
• All bundled skills updated to 1.1.0: English guides, user-language explanations, current CLI examples, and explicit network/payment safety boundaries.

Verification

• Full offline regression suite, Ruff, and Linux/Windows-platform mypy.
• Built wheel installed with tui/postprocess extras in an isolated Python 3.13 environment.
• Authorized source CLI Gemini native nano-banana-2 generation returned one saved image. Live TUI paid execution and native follow-up editing were not tested; gateway/model availability is not guaranteed.

Install

uv tool install "imagen-cli[tui,postprocess]"
# Existing installation:
uv tool upgrade imagen-cli
imagen skills update

v0.1.5

Patch release fixing Windows CI compatibility.

• Use explicit platform branches for terminal key-reader type checking.
• Isolate USERPROFILE in the empty XDG configuration fallback test on Windows.

Validation: the preceding fix commit passed all nine OS/Python CI jobs; the 0.1.5 release tree passed 1457 offline tests (2 skipped), Ruff, and Linux/Windows-platform mypy.

Published on PyPI: https://pypi.org/project/imagen-cli/0.1.5/

Full installation (including TUI and postprocessing): uv tool install "imagen-cli[tui,postprocess]".

v0.1.4

Skills install into the shared .agents/skills directory by default, with a checklist picker: arrows move, space toggles, a selects all, enter confirms, q cancels. The shared directory and any agent directory already present in the project start ticked; --target still selects specific agents and --target all selects every one.

skills list now scans every agent directory, so a copy installed for any agent is reported with its version. skills update treats an identical copy without a manifest as current and reports a differing one as unmanaged instead of failing with "not managed".

Fixes: an empty .agents directory no longer preselects 25 agents, agents installed under HOME no longer count as project detections, an empty XDG_CONFIG_HOME no longer resolves to a relative path, and imagen help <group> lists the commands in that group instead of claiming an unknown target.

Install: uv tool install "imagen-cli[tui,postprocess]", then imagen update to check.

Full Changelog: v0.1.3...v0.1.4