Image generation from the terminal. GPT Image 2 free on your ChatGPT Plus/Pro subscription — no OpenAI API key, no metered billing. Plus Nano Banana (Gemini) and GPT-5 Image. One CLI.
Type a prompt. Get an image. One command, zero browser tabs. nanaban is a CLI for AI image generation that works for humans typing prompts and LLM agents calling --json. It runs OpenAI's GPT Image 2 (free against your ChatGPT Plus/Pro subscription via Codex OAuth), Google's Nano Banana (Gemini), and OpenAI GPT-5 Image — pick whichever, or let nanaban choose based on the auth you have.
Install · Quick Start · Models · Auth · Usage · Agent Mode · Contributing
 nanaban "cyberpunk tokyo street neon rain" --ar wide
|
 nanaban "minimalist single line fox"
|
 nanaban "product photo white ceramic mug"
|
Every image on this page was generated with nanaban. Straight from the terminal.
Most AI image generators make you open a browser, wait in a queue, click through UI, and download manually. That workflow breaks the second you need images inside a script, a CI pipeline, or an agent loop.
nanaban fixes that:
- One command — type your prompt, get a file. No browser, no signup flow, no queue.
- Free GPT Image 2 for ChatGPT Plus/Pro subscribers. nanaban reads the OAuth token written by
codex loginand hits the private Codex backend (chatgpt.com/backend-api/codex/responses) on your behalf — every generation decrements your ChatGPT image quota, not your OpenAI API balance. Zero marginal cost, no API key needed. - Three model families, one CLI — GPT Image 2 (OpenAI's April 2026 flagship) when Codex auth is present, Nano Banana (Gemini) for the cheap/fast default with extended ratios, GPT-5 Image for OpenAI's text/UI work via OpenRouter.
- Auto-names files —
"a fox in a snowy forest at dawn"becomesfox_snowy_forest_dawn.png. - Built for scripts — stdout is always the file path.
nanaban "a cat" | xargs openjust works. - Built for LLM agents —
--jsongives structured output with cost.nanaban agent-infois a machine-readable manifest of every model, flag, transport, and error code (with per-code recovery instructions). - Tiny footprint — one Node package, or one standalone binary with no runtime required.
Three options, pick whichever matches how you like to install CLIs:
Homebrew (macOS/Linux, no Node needed):
brew install paperfoot/tap/nanabanStandalone binary (no Node needed, pick your platform):
# macOS (Apple Silicon)
curl -L https://github.com/paperfoot/nanaban-cli/releases/latest/download/nanaban-darwin-arm64 -o /usr/local/bin/nanaban && chmod +x /usr/local/bin/nanaban
# macOS (Intel)
curl -L https://github.com/paperfoot/nanaban-cli/releases/latest/download/nanaban-darwin-x64 -o /usr/local/bin/nanaban && chmod +x /usr/local/bin/nanaban
# Linux (x86_64)
curl -L https://github.com/paperfoot/nanaban-cli/releases/latest/download/nanaban-linux-x64 -o /usr/local/bin/nanaban && chmod +x /usr/local/bin/nanaban
# Linux (arm64)
curl -L https://github.com/paperfoot/nanaban-cli/releases/latest/download/nanaban-linux-arm64 -o /usr/local/bin/nanaban && chmod +x /usr/local/bin/nanabannpm (if you already have Node 18+):
npm install -g nanabanFrom source:
git clone https://github.com/paperfoot/nanaban-cli.git
cd nanaban && npm install && npm linkThree paths. Pick the one you already have credentials for:
Free via ChatGPT Plus/Pro (recommended if you have a sub):
# One-time: log in with your ChatGPT account
codex login
# Then just:
nanaban "a fox in snow" # uses GPT Image 2, billed to your ChatGPT sub ($0)OpenRouter (one key for Nano Banana AND GPT-5 Image):
# Get a key from https://openrouter.ai/keys
export OPENROUTER_API_KEY=sk-or-v1-...
nanaban "a fox in snow" # uses Nano Banana 2
nanaban "a fox in snow" --model gpt5-mini # uses GPT-5 Image MiniGemini direct (free tier available):
# Get a key from https://aistudio.google.com/apikey
nanaban auth set AIzaSy...
nanaban "a fox in snow"You only need one path configured. nanaban detects what's available and routes automatically. Run nanaban auth to see what's reachable. The default model auto-switches to gpt-image-2 when Codex auth is present, otherwise nb2.
| Id | Family | Best for | Aspect ratios | Sizes | ~Cost/img |
|---|---|---|---|---|---|
gpt-image-2 (default with Codex auth) |
OpenAI | Strong text, agentic planning, high-fidelity | 1:1, 2:3, 3:2 | 1K only | $0 on ChatGPT Plus/Pro |
nb2 (default without Codex) |
Gemini Nano Banana 2 | Fast, cheap, full ratio range | All + extended (1:4, 4:1, 1:8, 8:1) | 0.5K–4K | $0.067 |
nb2-pro (--pro) |
Gemini Nano Banana Pro | Higher quality detail | Standard 10 | 1K–4K | $0.136 |
gpt5 |
OpenAI GPT-5 Image | Strong text/UI rendering | 1:1, 2:3, 3:2 | 1K only | $0.193 |
gpt5-mini |
OpenAI GPT-5 Image Mini | Cheaper OpenAI option | 1:1, 2:3, 3:2 | 1K only | $0.041 |
Aliases: gi2/img2/images2 → gpt-image-2, pro → nb2-pro, flash → nb2, mini → gpt5-mini, gpt → gpt5.
Costs are typical per-image rates via the standard paid API path. gpt-image-2 is free when routed through Codex OAuth because it decrements your ChatGPT Plus/Pro image quota rather than an API balance.
nanaban detects credentials in this order and routes automatically. Any single path is enough.
| Source | Reaches | How to set |
|---|---|---|
~/.codex/auth.json (Codex OAuth) |
gpt-image-2 at $0 |
codex login |
OPENROUTER_API_KEY env |
nb2, nb2-pro, gpt5, gpt5-mini |
env var |
| Stored OpenRouter key | same as above | nanaban auth set-openrouter <key> |
GEMINI_API_KEY / GOOGLE_API_KEY |
nb2, nb2-pro |
env var |
| Stored Gemini key | nb2, nb2-pro |
nanaban auth set <key> |
| Gemini OAuth | nb2, nb2-pro |
~/.gemini/oauth_creds.json + OAuth client creds |
- Preference order:
codex-oauth→openrouter→gemini-direct.codex-oauthcomes first because it's free for Plus/Pro subscribers. - Automatic fallback: if the preferred transport returns a transient failure (
RATE_LIMITED,NETWORK_ERROR,AUTH_INVALID,AUTH_EXPIRED) nanaban retries on the next available transport. The success envelope gains afallbacksarray so the caller sees what happened. --via <transport>pins a route. No fallback when explicit. Aliases:codex/plus→codex-oauth,gemini/google→gemini-direct,or→openrouter.
Recommended stack for agents: codex login + OPENROUTER_API_KEY. gpt-image-2 is free, OpenRouter is the failover for other models. Check what's reachable with nanaban auth.
nanaban "prompt" # auto-picks best model for your auth
nanaban "prompt" -o sunset.png # custom filename
nanaban "prompt" --ar wide --size 2k # 16:9, high resolution (Gemini only)
nanaban "prompt" --pro # Nano Banana Pro
nanaban "prompt" --model gpt-image-2 # force GPT Image 2 (needs Codex auth)
nanaban "prompt" --model gpt5-mini # force GPT-5 Image Mini
nanaban "prompt" --via codex-oauth # force the ChatGPT sub route
nanaban "prompt" --neg "blurry, text" # negative prompt (Gemini only)
nanaban "prompt" -r style.png # reference image
nanaban edit photo.png "add sunglasses" # edit existing image (works with every model)| Flag | What it does | Default |
|---|---|---|
-o, --output <file> |
Output path | auto from prompt |
--ar <ratio> |
Aspect ratio (see table below) | 1:1 |
--size <size> |
Resolution: 0.5k 1k 2k 4k (model-dependent) |
1k |
--pro |
Use Nano Banana Pro (alias for --model nb2-pro) |
off |
--model <id> |
gpt-image-2, nb2, nb2-pro, gpt5, gpt5-mini |
auto (gpt-image-2 with Codex auth, else nb2) |
--via <transport> |
codex-oauth, gemini-direct, openrouter |
auto |
--neg <text> |
Negative prompt (Gemini only) | |
-r, --ref <file> |
Reference image (style/content guidance) | |
--open |
Open in default viewer after generating | off |
--json |
Structured JSON output for scripts | off |
--quiet |
Suppress non-essential output | off |
14 aspect ratios, from square to extreme panoramic:
| Ratio | Shorthand | Good for |
|---|---|---|
1:1 |
square |
Profile pics, thumbnails |
4:3 |
Photos, slides | |
3:2 |
Classic photo format | |
5:4 |
Print, posters | |
16:9 |
wide |
Hero images, banners, wallpapers |
21:9 |
ultrawide |
Cinematic, ultrawide monitors |
4:1 |
panoramic |
Panoramas, website headers |
8:1 |
banner |
Extreme banners, ribbons |
3:4 |
Portrait photos | |
2:3 |
portrait |
Book covers, tall posters |
4:5 |
Instagram portrait | |
9:16 |
tall / story |
Phone wallpapers, stories |
1:4 |
Tall strips, infographic panels | |
1:8 |
Extreme vertical banners |
Note: 1:4/4:1/1:8/8:1 are NB2-only. NB2 Pro supports the standard 10. GPT Image 2 and GPT-5 Image / Mini support only 1:1, 2:3, 3:2 (mapped to 1024×1024 / 1024×1536 / 1536×1024). nanaban surfaces capability mismatches as CAPABILITY_UNSUPPORTED errors before any HTTP call.
Pass any image as a style or content reference with -r:
nanaban "portrait of a woman" -r painting_style.png
nanaban "modern living room" -r color_palette.jpg
nanaban "product shot" -r brand_reference.pngThe model picks up on the visual language of your reference — color palette, composition, texture, artistic style — and applies it to your prompt. Useful for keeping a consistent look across a batch of images, matching brand aesthetics, or steering output toward a specific vibe without writing a 200-word prompt.
nanaban edit photo.png "remove the background"
nanaban edit headshot.png "make it a pencil sketch"
nanaban edit product.png "place on a marble table" --ar wideTakes a source image and your edit instruction. Same flags apply — pick a model, change aspect ratio, resolution, or use Pro for finer edits.
--json gives machine-readable output. No spinners, no colors, no ambiguity:
nanaban "a red circle" --json{
"status": "success",
"file": "/Users/you/red_circle.png",
"model": "gpt-image-2",
"transport": "codex-oauth",
"dimensions": { "width": 1024, "height": 1024 },
"size_bytes": 1247283,
"duration_ms": 12400,
"cost_usd": 0
}cost_usd is 0 for codex-oauth (billed against your ChatGPT sub), and reflects actual cost for OpenRouter/Gemini paid paths.
Errors come back in the same shape, with a hint the agent can act on:
{
"status": "error",
"code": "AUTH_MISSING",
"message": "No authentication configured. GPT Image 2 needs one of Codex OAuth (run `codex login`).",
"hint": "pick one: `codex login` (free gpt-image-2 via ChatGPT Plus/Pro) | `nanaban auth set-openrouter <key>` | set GEMINI_API_KEY / OPENROUTER_API_KEY."
}When auto-fallback kicks in and eventually succeeds, the success envelope carries a fallbacks audit trail:
{
"status": "success",
"file": "/Users/you/fox_snow.png",
"transport": "openrouter",
"fallbacks": [
{ "transport": "codex-oauth", "code": "RATE_LIMITED", "message": "..." }
]
}Error codes: AUTH_MISSING, AUTH_INVALID, AUTH_EXPIRED, PROMPT_MISSING, IMAGE_NOT_FOUND, GENERATION_FAILED, RATE_LIMITED, NETWORK_ERROR, MODEL_NOT_FOUND, TRANSPORT_UNAVAILABLE, CAPABILITY_UNSUPPORTED.
Exit codes: 0 success, 1 runtime error, 2 usage error.
Discover everything machine-readably: nanaban agent-info.
stdout is always just the file path. Metadata goes to stderr. These compose naturally:
nanaban "a cat" | xargs open # generate and open
nanaban "a cat" 2>/dev/null | pbcopy # copy path to clipboard
cat prompts.txt | while read p; do nanaban "$p"; done # batch generatenanaban ships a tiny skill file so Claude Code, Codex, and Gemini know when to invoke it:
nanaban skill install # writes ~/.claude/skills/nanaban/SKILL.md and peers
nanaban skill status # shows where it's installedThe skill description is intentionally terse — the full capability surface lives in nanaban agent-info, which the agent queries on demand. This keeps the skill stable across nanaban versions.
Your prompt becomes the filename. Common words get stripped, capped at 6 words, joined with underscores:
"a fox in a snowy forest at dawn" -> fox_snowy_forest_dawn.png
Collisions auto-increment: fox_snowy_forest.png, fox_snowy_forest_2.png, fox_snowy_forest_3.png.
Deliberately small:
@google/genai+google-auth-library— Gemini API accesscommander— CLI parsing (~90KB)nanospinner— terminal spinner (~3KB)picocolors— terminal colors (~3KB)tsx+typescript— runs TypeScript source directly in npm/source installs- OpenRouter, OpenAI Codex bridge — plain
fetch, no SDK - Standalone binaries bundle everything via
bun build --compile
Contributions welcome. See CONTRIBUTING.md for guidelines.
Built by Boris Djordjevic at 199 Biotechnologies | Paperfoot AI
