Nanaban CLI

Nanaban is a terminal-based AI image generator that turns text prompts into images in one command, with the standout feature being free GPT Image 2 generation for ChatGPT Plus and Pro subscribers via Codex OAuth.

What is Nanaban?

Nanaban (nanaban-cli on GitHub) is an open-source command-line tool that unifies three AI image generation backends under a single nanaban command. Built by Boris Djordjevic at Paperfoot AI / 199 Biotechnologies, it ships as a Homebrew formula, an npm package, and standalone bun-compiled binaries for macOS and Linux. The pitch is simple: "Type a prompt. Get an image. One command, zero browser tabs."

The headline feature: it reads the OAuth token written by the codex login command and proxies image generation through ChatGPT's backend, which means GPT Image 2 generations decrement your ChatGPT Plus or Pro image quota instead of an OpenAI API balance. For Plus/Pro subscribers, that is zero marginal cost with no API key required.

What it does

• Free GPT Image 2 via Codex OAuth — uses your existing ChatGPT Plus/Pro subscription quota.
• Three backends unified — GPT Image 2 (OpenAI), Nano Banana 2 / Pro (Google Gemini), and GPT-5 Image / Mini (OpenAI via OpenRouter).
• Auto-naming — "a fox in a snowy forest at dawn" becomes fox_snowy_forest_dawn.png. Collisions auto-increment.
• 14 aspect ratios — from square to extreme panoramic (1:8 and 8:1) on Nano Banana 2.
• Image editing and style references — nanaban edit photo.png "make it a pencil sketch" and -r style.png for visual guidance.
• Script-friendly output — stdout is the file path only; metadata to stderr for clean piping.
• Agent mode — --json returns structured output with cost, duration, dimensions, and fallback audit trails for LLM agents.
• Skill installation — nanaban skill install registers it with Claude Code, Codex, and Gemini so agents can call it directly.
• Standalone binaries — bun-compiled executables for macOS/Linux with no Node.js runtime required.

How it works

Auth is auto-detected in priority order: (1) Codex OAuth if codex login has been run, routes to GPT Image 2 for free, (2) OpenRouter API key for Nano Banana and GPT-5 variants, (3) Gemini API key for direct Google access. You can also pin a transport explicitly with --via codex-oauth|openrouter|gemini-direct.

When the preferred transport fails — rate limit, expired auth, network blip — nanaban auto-falls back to the next available backend. The agent mode surfaces the fallback chain in its JSON output so an LLM caller knows which model actually produced the image.

Who it is for

• ChatGPT Plus/Pro subscribers who want to use their existing image quota from the terminal without opening a browser.
• Developers building image-generation pipelines that need a script-friendly CLI rather than a SDK integration.
• LLM agents — Claude Code, Codex, and Gemini agents can install the Skill and call nanaban as a tool.
• Cost-conscious creators comparing free GPT Image 2 against cheap Gemini Nano Banana 2 ($0.067/image) for batch work.
• Anyone tired of browser-based image generation for routine work.

What you can build

• A prompts.txt batch runner that produces dozens of variations in a single while-loop.
• An LLM-driven thumbnail generator that calls nanaban from a Claude Code agent.
• A panoramic banner pipeline using Nano Banana 2's 8:1 ratio.
• A pencil-sketch headshot converter using nanaban edit.
• A CI/CD step that generates social-media assets from PR titles.
• A style-locked product-shot generator that uses a single reference image across many prompts.

Why it matters

GPT Image 2 launched in April 2026 as OpenAI's strongest image model. The standard path to using it is the OpenAI API at per-image pricing or the ChatGPT web app with a quota. Nanaban opens a third path — terminal-native, script-friendly, and free for ChatGPT Plus/Pro subscribers — which is exactly the gap that matters for developers, agent builders, and anyone running image generation as part of a real workflow rather than a one-off creative ask.

1. Install

Homebrew (recommended on macOS):

brew install paperfoot/tap/nanaban

npm (Node 18+):

npm install -g nanaban

Standalone binary (macOS Apple Silicon example):

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

2. Authenticate

For the free path via ChatGPT Plus/Pro, install Codex CLI and log in:

codex login

Or set an OpenRouter / Gemini API key for the paid backends:

nanaban auth set-openrouter
nanaban auth set

3. Generate your first image

nanaban "cyberpunk tokyo street neon rain"

The file lands in the current directory with an auto-generated name.

4. Install as a Skill for agents

nanaban skill install

This registers nanaban with Claude Code, Codex, and Gemini so an agent can call it as a tool.