imggen-cli

# imggen `imggen` is an installable Go CLI and stdio MCP server that lets AI agents generate images locally through Modal serverless GPUs. The Go control plane handles CLI arguments, config, resolution validation, and output naming; the Python + Modal execution plane runs HiDream inference on A100s and returns generated PNG payloads to Go, which writes them as local files. ## Current Status - **HiDream dev model** (`hidream-o1-dev`): validated with real smoke tests at 1k resolution. - **HiDream full model** (`hidream-o1`): code path exists but full-model smoke tests at 2k are pending. - `flash-attn` support is deferred due to Modal build-container OOM. ## Quick Start ### Prerequisites - **Go** 1.26.3+ - **Python** 3.11 with **uv** 0.7.12+ - **Modal** CLI installed and authenticated ### 1. Authenticate with Modal ```bash pip install modal modal token set ``` ### 2. Create a Hugging Face token secret HiDream downloads weights from Hugging Face. Provide your token as a Modal secret (do not commit it): ```bash modal secret create huggingface-token HF_TOKEN=<your_token> ``` Replace `<your_token>` with your actual Hugging Face access token. ### 3. Install ```bash go install github.com/carlos0934/imggen-cli/cmd/imggen@latest ``` For local development from this repository, you can also run `make install`. ### 4. Generate your first image ```bash imggen generate --prompt "a serene mountain landscape" ``` For multiple images with custom settings: ```bash imggen generate --prompt "a cyberpunk city" --number 4 --resolution 2k --aspect-ratio 16:9 --seed 42 ``` ### CLI Parameters | Parameter | Default | Description | |-----------|---------|-------------| | `--prompt` | required | Text prompt used to generate the image. | | `--model` | `hidream-o1` | Model to run. Supported values: `hidream-o1` and `hidream-o1-dev`. | | `--output` | `output` | Local output directory where Go writes generated PNG files. | | `--number` | `1` | Number of images to generate. Accepted range: `1` to `4`. | | `--resolution` | `1k` | Resolution preset. Supported values: `1k`, `2k`. | | `--aspect-ratio` | `1:1` | Aspect ratio preset. Supported values: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`. | | `--seed` | random | Optional integer seed. When `--number` is greater than 1, each image increments the seed by 1. | Example with deterministic multi-image output: ```bash imggen generate \ --prompt "an elven knight in a crystal forest" \ --model hidream-o1-dev \ --resolution 1k \ --aspect-ratio 1:1 \ --number 3 \ --seed 42 \ --output output ``` This uses seeds `42`, `43`, and `44`, then writes local PNG files under `output/`. ## MCP Server Usage Start the stdio MCP server: ```bash imggen mcp ``` Exposed tools: - `generate_image(prompt, model?, output?, number?, resolution?, aspect_ratio?, seed?) → string[]` - `list_models() → {name, repo}[]` - `ping() → {status: "ok"}` ### Example Agent Configuration To use `imggen` as an MCP server in an agent that supports stdio transports, configure the agent to run `imggen mcp`: ```json { "mcpServers": { "imggen": { "command": "imggen", "args": ["mcp"] } } } ``` If `imggen` is not on the agent process `PATH`, use the full path to the installed binary, for example `C:\Users\<you>\go\bin\imggen.exe` on Windows. All tool schemas are typed; no `map[string]any` input is used. ## Configuration Config is loaded from `{UserConfigDir}/imggen/config.yaml` (no custom `--config` flag in v1). If the file is missing, built-in defaults are used. Example: ```yaml models: - name: hidream-o1 repo: HiDream-ai/HiDream-O1-Image ``` ## Resolution & Aspect Ratio | Resolution | Long edge | 1:1 | 16:9 | 9:16 | 4:3 | 3:4 | |-----------|-----------|-----|------|------|-----|-----| | 1k | 1024 | 1024×1024 | 1024×576 | 576×1024 | 1024×768 | 768×1024 | | 2k | 2048 | 2048×2048 | 2048×1152 | 1152×2048 | 2048×1536 | 1536×2048 | Only the presets above are accepted; custom ratios are rejected. ## Outputs Generated images are saved as local files by the Go control plane: - Single: `{timestamp}-{memorable-word}.png` - Multi: `{timestamp}-{memorable-word}-{index}.png` `timestamp` uses `year-month-day-hour` (e.g., `20260606-14`). `memorable-word` is chosen from an embedded 256-word English RPG/video-game vocabulary. The Modal Volume (`imggen-model-cache`) is used **only** for Hugging Face model cache. Generated outputs are **not** fetched from Modal Volume; they are written locally by Go after parsing the JSON payload returned by Modal. ## Project Structure ``` . ├── cmd/imggen/main.go # CLI entry point ├── internal/ │ ├── cli/generate.go # generate subcommand │ ├── config/config.go # XDG config loading │ ├── model/ │ │ ├── registry.go # model registry │ │ └── size.go # resolution / aspect ratio → width×height │ ├── mcp/ │ │ ├── server.go # stdio MCP server │ │ ├── tools.go # typed tool definitions │ │ └── cmd.go # mcp cobra subcommand │ ├── output/namer.go # timestamp + memorable word filenames │ └── provider/modal.go # modal run wrapper └── python/ ├── pyproject.toml └── src/imggen_runtime/ ├── config.py # Resolution / AspectRatio dataclasses ├── generation.py # generation orchestration ├── hidream/ │ ├── __init__.py # MIT attribution │ └── generate.py # HiDream inference wrapper └── modal_app.py # Modal app definition ``` ## License MIT