imagine-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

imagine CLI

imagine

is a multi-provider image-generation CLI. One binary, one YAML config file, three providers (gemini, vertex, openai).

-p "..."

generates; add

-i reference.png

and it edits — no separate subcommand.

imagine

是一款支持多提供商的图像生成CLI工具。只需一个二进制文件、一个YAML配置文件，即可对接三个提供商（gemini、vertex、openai）。使用

-p "..."

生成图像；添加

-i reference.png

即可进入编辑模式——无需单独的子命令。

When to use

适用场景

Use this skill whenever the user:

Mentions the
```
imagine
```
command, any of its flags, providers (gemini, vertex, openai), or model aliases (
```
gpt-image-2
```
,
```
pro
```
,
```
flash
```
,
```
1.5
```
, etc.)
Wants to generate or edit images from the command line
Is setting up the tool for the first time
Hits an error they don't understand (most imagine errors are self-explanatory but the full list + fixes live in references/troubleshooting.md)
Asks which provider to pick for a task
References sizes (
```
1K
```
,
```
2K
```
,
```
4K
```
,
```
1024x1024
```
,
```
3840x2160
```
, etc.)

当用户出现以下情况时，适用本技能：

提及
```
imagine
```
命令、其任意参数、提供商（gemini、vertex、openai）或模型别名（
```
gpt-image-2
```
、
```
pro
```
、
```
flash
```
、
```
1.5
```
等）
希望通过命令行生成或编辑图像
首次设置该工具
遇到无法理解的错误（多数imagine错误自带说明，但完整错误列表及修复方案请查看 references/troubleshooting.md）
询问针对某项任务应选择哪个提供商
提及图像尺寸（
```
1K
```
、
```
2K
```
、
```
4K
```
、
```
1024x1024
```
、
```
3840x2160
```
等）

Workflow

工作流程

Always walk these three pre-flight steps before running an imagine command.

在运行imagine命令前，务必完成以下三项预检查步骤。

Step 1 — Is imagine installed?

步骤1 — 是否已安装imagine？

bash

command -v imagine || echo NOT_INSTALLED

NOT_INSTALLED

, decide the install method automatically — don't prompt the user to pick.

Decision: check for Go first. If the user has Go, install from source (faster, keeps the binary up-to-date with

go install …@latest

on re-runs). Otherwise fall back to the pre-built binary.

bash

if command -v go >/dev/null 2>&1; then
  go install github.com/AhmedAburady/imagine-cli/cmd/imagine@latest
else
  # Detect platform, pick the matching release asset
  case "$(uname -s)-$(uname -m)" in
    Darwin-arm64)  ASSET=imagine-darwin-arm64 ;;
    Darwin-x86_64) ASSET=imagine-darwin-amd64 ;;
    Linux-x86_64)  ASSET=imagine-linux-amd64 ;;
    Linux-aarch64|Linux-arm64) ASSET=imagine-linux-arm64 ;;
    *) echo "Unsupported platform — download manually from https://github.com/AhmedAburady/imagine-cli/releases/latest"; exit 1 ;;
  esac
  curl -L -o imagine "https://github.com/AhmedAburady/imagine-cli/releases/latest/download/$ASSET"
  chmod +x imagine
  sudo mv imagine /usr/local/bin/imagine
fi

After install, verify:

bash

imagine --version

Windows users: download

imagine-windows-amd64.exe

(or

-arm64.exe

) from the releases page, rename to

imagine.exe

, and place on

%PATH%

bash

command -v imagine || echo NOT_INSTALLED

如果返回

NOT_INSTALLED

，请自动选择安装方式——不要让用户手动选择。

决策逻辑： 先检查是否安装Go。若已安装Go，则从源码安装（速度更快，重新运行

go install …@latest

即可保持二进制文件更新）。否则使用预编译二进制文件。

bash

if command -v go >/dev/null 2>&1; then
  go install github.com/AhmedAburady/imagine-cli/cmd/imagine@latest
else
  # 检测平台，选择匹配的发布资源
  case "$(uname -s)-$(uname -m)" in
    Darwin-arm64)  ASSET=imagine-darwin-arm64 ;;
    Darwin-x86_64) ASSET=imagine-darwin-amd64 ;;
    Linux-x86_64)  ASSET=imagine-linux-amd64 ;;
    Linux-aarch64|Linux-arm64) ASSET=imagine-linux-arm64 ;;
    *) echo "不支持的平台——请从https://github.com/AhmedAburady/imagine-cli/releases/latest手动下载"; exit 1 ;;
  esac
  curl -L -o imagine "https://github.com/AhmedAburady/imagine-cli/releases/latest/download/$ASSET"
  chmod +x imagine
  sudo mv imagine /usr/local/bin/imagine
fi

安装完成后，验证：

bash

imagine --version

Windows用户：从发布页面下载

imagine-windows-amd64.exe

（或

-arm64.exe

），重命名为

imagine.exe

，并放置在

%PATH%

路径下。

Step 2 — Does the config file exist with at least one provider?

步骤2 — 配置文件是否存在且至少包含一个提供商？

bash

cat ~/.config/imagine/config.yaml 2>/dev/null \
  || cat ~/.config/imagine/config.yml 2>/dev/null \
  || echo NO_CONFIG

Windows path:

%AppData%\imagine\config.yaml

If missing or the

providers:

block is empty, walk the user through creating one. Full schema and per-provider credential setup in references/config.md. A ready-to-copy template sits at assets/config.example.yaml.

Minimal Gemini-only example:

yaml

default_provider: gemini
providers:
  gemini:
    api_key: AIza-paste-key-here

bash

cat ~/.config/imagine/config.yaml 2>/dev/null \
  || cat ~/.config/imagine/config.yml 2>/dev/null \
  || echo NO_CONFIG

Windows路径：

%AppData%\imagine\config.yaml

。

如果配置文件缺失或

providers:

块为空，引导用户创建配置文件。完整配置 schema 及各提供商凭证设置请查看 references/config.md。可直接复制的模板位于 assets/config.example.yaml。

仅配置Gemini的最简示例：

yaml

default_provider: gemini
providers:
  gemini:
    api_key: AIza-paste-key-here

Step 3 — Resolve the active provider

步骤3 — 确定当前激活的提供商

Every

imagine

invocation runs under one active provider. Precedence:

--provider <name>          (CLI flag — highest)
  ↓
default_provider           (config.yaml)
  ↓
first under providers:     (alphabetical)
  ↓
error

imagine providers show

prints the current state with

[active]

and

[default]

markers — use it when there's ambiguity.

每次调用

imagine

都会基于一个激活的提供商运行，优先级顺序如下：

--provider <名称>          （CLI参数——优先级最高）
  ↓
default_provider           （config.yaml中的配置）
  ↓
providers下的第一个提供商  （按字母顺序）
  ↓
报错

imagine providers show

命令会打印当前状态，标记

[active]

（激活）和

[default]

（默认）——存在歧义时可使用该命令。

Common flags (every provider)

通用参数（所有提供商适用）

Flag	Long	Purpose
`-p`	`--prompt`	Prompt (required). Also accepts a file path.
`-o`	`--output`	Output folder (default `.` )
`-f`	`--filename`	Output filename. Extension ( `.png` / `.jpg` / `.webp` ) drives format. With `-n >1` , `_1` , `_2` , … suffixes.
`-n`	`--count`	1-20 images
`-i`	`--input`	Reference image/folder, repeatable. Flips to edit mode.
`-r`	`--replace`	Use input filename for output (single `-i` only; mutually exclusive with `-f` )
	`--provider`	Per-invocation override

短选项	长选项	用途
`-p`	`--prompt`	提示词（必填）。也支持传入文件路径。
`-o`	`--output`	输出文件夹（默认当前目录 `.` ）
`-f`	`--filename`	输出文件名。扩展名（ `.png` / `.jpg` / `.webp` ）决定图像格式。当 `-n >1` 时，会添加 `_1` 、 `_2` … 后缀。
`-n`	`--count`	生成1-20张图像
`-i`	`--input`	参考图像/文件夹，可重复使用。触发编辑模式。
`-r`	`--replace`	使用输入文件名作为输出文件名（仅适用于单个 `-i` ；与 `-f` 互斥）
	`--provider`	单次调用时覆盖默认提供商

Provider-specific flags

提供商专属参数

Flags that don't belong to the active provider are rejected with a clear error. Deep detail per provider:

Gemini / Vertex → references/gemini.md. Flags:
```
-m pro/flash
```
,
```
-s 1K/2K/4K
```
,
```
-a aspect-ratio
```
,
```
-g grounding
```
,
```
-t thinking
```
(flash only),
```
-I image-search
```
(gemini flash only).
OpenAI → references/openai.md. Flags:
```
-m gpt-image-2 family
```
,
```
-s shorthand/raw WxH
```
,
```
-q quality
```
,
```
--compression
```
,
```
--moderation
```
,
```
--background
```
. Includes the full size matrix and edit-mode size restriction.

When the user is unsure which provider to pick:

Photorealism, text rendering, intricate prompts → OpenAI
gpt-image-2
Fast iteration, Google ecosystem, live-search grounding → Gemini or Vertex
GCP-native auth / enterprise quotas → Vertex

不属于当前激活提供商的参数会被拒绝并返回清晰错误。各提供商详细说明：

Gemini / Vertex → references/gemini.md。参数：
```
-m pro/flash
```
、
```
-s 1K/2K/4K
```
、
```
-a aspect-ratio
```
、
```
-g grounding
```
、
```
-t thinking
```
（仅flash支持）、
```
-I image-search
```
（仅gemini flash支持）。
OpenAI → references/openai.md。参数：
```
-m gpt-image-2 family
```
、
```
-s shorthand/raw WxH
```
、
```
-q quality
```
、
```
--compression
```
、
```
--moderation
```
、
```
--background
```
。包含完整尺寸矩阵及编辑模式下的尺寸限制。

当用户不确定选择哪个提供商时：

追求照片级真实感、文字渲染、复杂提示词 → OpenAI
gpt-image-2
快速迭代、Google生态、实时搜索 grounding → Gemini 或 Vertex
GCP原生认证 / 企业配额 → Vertex

Describe subcommand

Describe子命令

bash

imagine describe -i photo.jpg                   # plain text
imagine describe -i ./styles/ -json -o style.json
imagine describe -i photo.jpg -vertex           # Vertex backend

Gemini/Vertex only — describe doesn't support OpenAI. Needs either

providers.gemini.api_key

providers.vertex.provider_options.gcp_project

configured. If the user has only OpenAI configured, describe prints friendly setup instructions (with

gcloud auth application-default login

for Vertex) and exits.

bash

imagine describe -i photo.jpg                   # 纯文本描述
imagine describe -i ./styles/ -json -o style.json
imagine describe -i photo.jpg -vertex           # 使用Vertex后端

仅Gemini/Vertex支持 — describe子命令不支持OpenAI。需要配置

providers.gemini.api_key

或

providers.vertex.provider_options.gcp_project

。如果用户仅配置了OpenAI，describe命令会打印友好的设置指引（包括Vertex的

gcloud auth application-default login

命令）并退出。

Examples

示例

bash

undefined

bash

undefined

Generate (active provider from config)

生成图像（使用配置中的激活提供商）

imagine -p "a sunset over mountains"

imagine -p "山间日落"

Batch with size + aspect (Gemini/Vertex)

批量生成并指定尺寸和宽高比（Gemini/Vertex）

imagine -p "cityscape" -n 3 -s 2K -a 16:9 -o ./city

imagine -p "城市景观" -n 3 -s 2K -a 16:9 -o ./city

OpenAI — fast draft

OpenAI — 快速生成草稿

imagine -p "logo idea" --provider openai -q low

imagine -p "logo创意" --provider openai -q low

OpenAI — 4K hero banner as JPEG

OpenAI — 生成4K英雄横幅JPEG图

imagine -p "hero banner" --provider openai -s 3840x2160 -q high -f hero.jpg

imagine -p "英雄横幅" --provider openai -s 3840x2160 -q high -f hero.jpg

Edit, keep input filename

编辑图像，保留输入文件名

imagine -p "add rain" -i photo.png -r

imagine -p "添加雨景" -i photo.png -r

Multi-reference edit (OpenAI supports up to 16 refs/call)

多参考图编辑（OpenAI单次调用最多支持16张参考图）

imagine -p "gift basket of these" --provider openai
-i lotion.png -i candle.png -i soap.png

imagine -p "将这些物品组成礼品篮" --provider openai
-i lotion.png -i candle.png -i soap.png

Vertex — same flags as Gemini, different auth

Vertex — 参数与Gemini相同，认证方式不同

imagine -p "a cat" --provider vertex -n 3


For more, run `imagine --help` — provider-aware help surfaces the active provider's flags and a tailored EXAMPLES block.

imagine -p "一只猫" --provider vertex -n 3


更多示例请运行 `imagine --help` — 提供商感知型帮助会显示当前激活提供商的参数及定制化的示例区块。

Anti-patterns — do NOT do these

反模式——请勿执行以下操作

Never suggest
```
GEMINI_API_KEY
```
,
```
OPENAI_API_KEY
```
, or any env var for credentials. imagine does not read env vars. Config file only.
Never suggest
```
imagine config set-*
```
— those commands don't exist. Users edit
```
config.yaml
```
directly.
Never use
```
-ar
```
,
```
-is
```
,
```
-vertex
```
as single-dash flags. They're
```
--aspect-ratio
```
,
```
--image-search
```
,
```
--provider vertex
```
. (Describe keeps its own legacy
```
-vertex
```
flag — the exception.)

Never combine

--background transparent

with

gpt-image-2

. Unsupported — use

-m 1.5

Never combine
```
-f
```
with
```
-r
```
— mutually exclusive.
Never suggest
```
--provider openai
```
for the describe subcommand. Describe is Gemini/Vertex only.

切勿建议使用
```
GEMINI_API_KEY
```
、
```
OPENAI_API_KEY
```
或任何环境变量存储凭证。imagine 不读取环境变量，仅支持配置文件。
切勿建议使用
```
imagine config set-*
```
命令——这些命令不存在。用户需直接编辑
```
config.yaml
```
。
切勿将
```
--aspect-ratio
```
、
```
--image-search
```
、
```
--provider vertex
```
写成单短横线形式（如
```
-ar
```
、
```
-is
```
、
```
-vertex
```
）。（Describe子命令保留了自己的旧版
```
-vertex
```
参数——此为例外情况。）
切勿将
```
--background transparent
```
与
```
gpt-image-2
```
组合使用——该组合不支持，请使用
```
-m 1.5
```
。
切勿同时使用
```
-f
```
和
```
-r
```
——二者互斥。
切勿建议对describe子命令使用
```
--provider openai
```
——Describe仅支持Gemini/Vertex。

Troubleshooting

故障排查

When imagine errors, read references/troubleshooting.md before guessing. Covers every error message the CLI can produce with its specific fix.

当imagine报错时，请先查看 references/troubleshooting.md 再尝试排查。该文档涵盖了CLI可能产生的所有错误消息及其对应的修复方案。