@yswgaicx/yswg-img-cli

v0.1.14

Published

4 days ago

CLI wrapper for YSWG Monkey Genius image generation.

0High
0Medium
0Low

yswgaicx

yswg-img-cli

yswg-img wraps the YSWG Monkey Genius image generation page as a CLI.

Install

Install from npm on any machine with Node.js 22 or newer:

npm install -g @yswgaicx/yswg-img-cli@latest
yswg-img --help

Upgrade an existing global install:

npm install -g @yswgaicx/yswg-img-cli@latest
yswg-img version --json

yswg-img checks npm for newer versions at most once every 12 hours and writes upgrade hints to stderr, so --json stdout stays parseable. Disable this check with --no-update-check or YSWG_IMG_CLI_NO_UPDATE_CHECK=1.

Install Locally

npm link

You can also run it without linking:

node bin/yswg-img.js --help

Login

Send the enterprise WeChat verification code:

yswg-img auth send-code --email zhangsan

yswg-img auth login --email zhangsan --code 123456

The token is saved to ~/.yswg-img-cli/config.json.

Agent Usage

Use these rules when an AI agent calls the CLI:

First run yswg-img auth status --json.
If authenticated is false, run yswg-img auth send-code --email <email> --json and then yswg-img auth login --email <email> --code <6 digits> --json.
Prefer --json for every command so downstream tools can parse stable output.
Use defaults unless the user explicitly asks otherwise: groupId=6, model gemini-3.1-flash-image-preview, ratio 1:1, count 1.
For one-shot generation, call:

yswg-img generate --prompt "一只可爱的白色兔子，粉色背景" --json

generate automatically checks live model health before submitting. If the selected model is slower than 90 seconds on average or has poor health, the CLI switches to a healthier image model and returns modelSwitch in JSON output.
If the user explicitly wants the selected model even when it is slow, add --no-auto-switch.
Read the local model cache without calling the backend:

yswg-img models --json

If model validation fails after backend permissions change, refresh the cache:

yswg-img models refresh --json

If the access token expires, authenticated backend commands automatically use the saved refresh token once, save the new session, and retry the original request.
Check whether the globally installed CLI is current:

yswg-img version --json

For up to 4 parallel images in one backend request, call:

yswg-img generate --prompt "四张电商产品场景图" --count 4 --json

For long-running jobs, wait for the command result. If it times out, recover it:

yswg-img tasks recover --task-id <task-id-from-json> --out outputs/recovered --json

For generated images, keep only local file paths and short summaries in agent context. Do not paste image bytes, base64, data:image/..., or full tool output into the conversation.
To fetch an Amazon product gallery by ASIN, call:

yswg-img amazon asin B0TEST1234 --max 7 --json

To call the backend SSE text stream endpoint, use:

yswg-img stream --prompt "用三句话总结这张图" --image-url https://example.com/a.png --json

Generate

Supported Monkey Genius options mirrored by the CLI:

Model/group selection: --group-id, --model
Model health protection: automatic live health check with --no-auto-switch for user-forced model selection
Aspect ratio: --ratio 1:1|3:2|2:3|4:3|3:4|16:9|9:16|5:4|4:5|21:9
Concurrent image output: --count 1 through --count 4 when the selected model supports it
Reference images: --ref ./a.png,https://example.com/b.jpg
Night/off-peak queue submission: --night
AI tool/template payloads: --template-code, --template-vars-json
Amazon ASIN product gallery lookup: amazon asin <asin> --max 7
Text / vision SSE invocation: stream --prompt <text>
Generation history lookup and timeout recovery: tasks search, tasks recover
History tabs/search/night-cancel: tasks search --tab ..., tasks cancel-night

Known display-name to vendor-model mapping:

groupId=2046043157249933314 displays as 图灵二代 and is sent as gpt-image-2.
groupId=2046853405565095939 displays as 图灵二代高清 and is sent as gpt-image-2-vip.
groupId=2046853405565095940 displays as 图灵二代超清 and is sent as gpt-image-2-vip.

The backend also overwrites params.model from the selected endpoint model, but the CLI mirrors the vendor model in dry-run output to avoid misleading agents.

Model Health Switching

Before a real generate request, the CLI calls:

GET /prod-api/web/ai-group-metrics/realtime

The response is parsed as a permission tree. Each model node is matched by groupId, and the CLI reads metrics.windows with preference for the 1-minute window, then 5/10/30/60 minutes.

Switching rules:

Default threshold: average successful duration above 90000ms.
Health threshold: success rate below 80%.
Only image-generation models are candidates.
Text models, video models, and exhausted models are excluded.
Backend remaining=-1 is treated as unlimited capacity; only an explicit remaining=0 is treated as exhausted.
Same-size models are preferred when possible.
If the healthier candidate does not support the requested ratio or image count, the CLI keeps the original model and writes a warning to stderr.
If the health endpoint fails, generation still proceeds with the originally selected model and writes a warning to stderr.

Force the exact selected model:

yswg-img generate --prompt "..." --group-id 6 --no-auto-switch --json

When switching happens, JSON output includes:

{
  "modelSwitch": {
    "fromGroupId": "6",
    "toGroupId": "5",
    "reason": "平均耗时 120000ms 超过 90000ms"
  }
}

Local reference images are compressed before OSS upload by default, matching the Monkey Genius frontend behavior:

Images below 50 KB are kept as-is.
Images are resized to fit within 1280 x 1280.
Opaque images are converted to JPEG at quality 0.82, then stepped down toward 0.5 until they are near 300 KB.
Images with transparency are kept as PNG.

Use --no-compress only when the original file must be uploaded unchanged.

Dry-run the backend payload:

yswg-img generate \
  --prompt "一张白底产品图，柔和自然光，高级电商摄影" \
  --ratio 1:1 \
  --count 1 \
  --dry-run \
  --json

Submit and wait for output images:

yswg-img generate \
  --prompt "一张白底产品图，柔和自然光，高级电商摄影" \
  --ratio 1:1 \
  --count 4 \
  --out outputs \
  --json

The CLI caps one generation request at 4 images. When the backend returns multiple task IDs, the CLI waits for those tasks concurrently and downloads the result files by path.

Downloaded file names include the invoke task batch prefix, for example 2065019349651689473-image-01.png. Re-running generation or recovery in the same --out directory will not overwrite existing files; repeated downloads add a numeric suffix such as -2.

For image-heavy workflows, keep local file paths and short summaries in agent context. Do not paste high-resolution image data, base64, data:image/..., or full tool output into the conversation.

Use reference images:

yswg-img generate \
  --prompt "参考产品主体，生成室内生活方式场景图" \
  --ref ./product.png,https://example.com/ref.jpg \
  --out outputs \
  --json

Use an AI tool/template payload:

yswg-img generate \
  --group-id 6 \
  --template-code tool_code \
  --template-vars-json '{"color":"red"}' \
  --display-prompt "AI 工具生成" \
  --dry-run \
  --json

If a long generation times out or the WebSocket disconnects, the CLI now checks generation history for the returned invoke task IDs before failing. This avoids submitting the same prompt again when the image was already produced.

Tune the wait timeout:

yswg-img generate --prompt "..." --timeout 900 --json

Query recent task history without creating a new generation task:

yswg-img tasks search --size 10 --keyword "兔子" --tab all --json

The CLI intentionally only queries the latest 10 records. If you need older records, open the navigation site and query them in the Monkey Genius page.

Available history tabs: all, expiring1d, expiring2d, nightQueue.

Fetch a history record by record ID:

yswg-img tasks get --id 2064983569742958594 --json

Recover/download completed images by invoke task ID after a timeout:

yswg-img tasks recover \
  --task-id 2065019349651689473 \
  --out outputs/recovered \
  --json

Cancel an off-peak queued task:

yswg-img tasks cancel-night --id <record-id> --json

Fetch Amazon product title and main image gallery by ASIN:

yswg-img amazon asin B0TEST1234 --max 7 --json

The command calls /prod-api/web/amazon/asin/{asin} and returns the backend AmazonProductVo shape: asin, title, and images.

Stream

yswg-img stream calls the backend SSE endpoint:

POST /prod-api/web/ai/invoke/stream

Default text model: groupId=13 (gemini-3-flash-preview).

Machine-readable call:

yswg-img stream --prompt "写一段短文介绍天才猴子" --json

Continue an existing conversation:

yswg-img stream \
  --prompt "继续上一个回答，改成要点列表" \
  --conversation-id <conversation-id> \
  --json

Use image URLs for vision input:

yswg-img stream \
  --prompt "分析这两张图片的差异" \
  --image-url https://example.com/a.png,https://example.com/b.png \
  --json

Pass advanced backend params or prompt templates:

yswg-img stream \
  --prompt "输出更短" \
  --params-json '{"temperature":0.2}' \
  --template-code image_analyze \
  --template-vars-json '{"tone":"short"}' \
  --json

With --json, stdout is a final summary object containing content, conversationId, message IDs, and usage when the backend returns them. Without --json, the CLI writes delta text as it arrives and appends one final newline.

Configuration

Runtime flags override environment variables, which override the saved config. The app ID is the exception: it is fixed to the npm app and cannot be overridden.

YSWG_TOKEN
YSWG_REFRESH_TOKEN
YSWG_BASE_URL
YSWG_WS_PATH
YSWG_IMG_CLI_NO_UPDATE_CHECK

Default app name: npm. Default app ID: 2066371323654864898. The app ID is fixed. --app-id and YSWG_APP_ID are intentionally rejected. Default ratio: 1:1. Default generation model: gemini-3.1-flash-image-preview (groupId=6, 三代).

Model Cache

yswg-img models --json reads local metadata from ~/.yswg-img-cli/model-cache.json. If that file does not exist, the CLI falls back to built-in npm app defaults. This keeps generation validation fast and stable for agents.

Run this only when backend model permissions or model metadata change:

yswg-img models refresh --json

If generation reports a model/group validation mismatch, refresh the cache before submitting the same task again.

Version Updates

Use yswg-img version --json for a machine-readable version check:

{
  "currentVersion": "0.1.8",
  "latestVersion": "0.1.9",
  "updateAvailable": true,
  "upgradeCommand": "npm install -g @yswgaicx/yswg-img-cli@latest"
}

Use yswg-img upgrade --json to print the canonical upgrade command without touching npm:

yswg-img upgrade --json

The CLI caches npm latest metadata in ~/.yswg-img-cli/update-check.json. Regular commands emit update hints to stderr only, preserving stdout for JSON parsers and agents.

Code Structure

bin/yswg-img.js: executable entrypoint only.
src/cli.js: command dispatch, dependency injection, JSON output, and agent help text.
src/stream.js: stream payload normalization and JSON flag parsing.
src/generate.js: generation payloads, validation, history recovery, WebSocket wait, uploads, downloads.
src/api.js: YSWG HTTP API client.
src/config.js: config loading, env/flag precedence, email normalization.
src/model-cache.js: built-in model metadata plus local cache refresh/read helpers.
src/version-check.js: npm latest lookup, update cache, version comparison, upgrade command.
src/args.js: minimal CLI argument parsing.
src/image-compress.js: frontend-compatible reference image compression.