nanobanana-cli

<p align="center">
  <img src="docs/images/icon.png" width="128" height="128" alt="nanobanana-cli">
</p>

<h1 align="center">nanobanana-cli</h1>

<p align="center">
  <strong>High-performance Rust CLI for image generation, editing, and Visual DNA extraction</strong><br>
  Powered by Google's Nano Banana 2 (<code>gemini-3.1-flash-image-preview</code>)
</p>

<p align="center">
  <a href="https://github.com/OhJayGee/nanobanana-cli/releases/latest"><img src="https://img.shields.io/github/v/release/OhJayGee/nanobanana-cli?style=flat-square&color=blue" alt="Release"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT License"></a>
  <a href="https://github.com/OhJayGee/nanobanana-cli/releases/latest"><img src="https://img.shields.io/github/downloads/OhJayGee/nanobanana-cli/total?style=flat-square&color=orange" alt="Downloads"></a>
  <img src="https://img.shields.io/badge/lang-Rust-orange?style=flat-square&logo=rust" alt="Rust">
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square" alt="Platform">
</p>

---

## Features

- **Multimodal Native** — Text-to-Image, Image+Text editing, and multi-image composition
- **Visual DNA Extraction** — Reverse-engineer the aesthetic DNA (lighting, style, materials, camera) of any image into structured JSON
- **DNA-Driven Consistency** — Feed DNA back into generation to maintain 100% aesthetic consistency across subjects
- **Surgical Editing** — Modify specific elements while preserving the original structure
- **Pro Controls** — 14 aspect ratios, 4 resolution tiers (up to 4K), thinking levels for reasoning depth
- **Universal Agent Skill** — Bundled skill for Gemini CLI, Claude Code, Cursor, and more
- **MCPB Extension** — Also available as a [one-click Claude Desktop extension](https://github.com/OhJayGee/nanobanana2-mcpb)

## Installation

### From source

```bash
git clone https://github.com/OhJayGee/nanobanana-cli.git
cd nanobanana-cli
cargo build --release
```

### Pre-built binaries

Download from [Releases](https://github.com/OhJayGee/nanobanana-cli/releases/latest) — available for macOS (Apple Silicon & Intel), Linux, and Windows.

### Agent Skill

Install across all AI agents (Gemini CLI, Claude Code, Cursor):

```bash
npx skills add https://github.com/OhJayGee/nanobanana-cli --skill nanobanana
```

The skill features progressive disclosure (loading guides only when needed) and auto-downloads the correct binary for your OS.

## Usage

### 1. Text-to-Image

```bash
./nanobanana-cli --prompt "a shiny red apple" --output "apple.png"
```

<p align="center">
  <img src="docs/images/apple.png" width="50%" />
</p>

### 2. Surgical Editing

```bash
./nanobanana-cli --image apple.png --prompt "change the color of the apple to green" --output "green_apple.png"
```

<p align="center">
  <img src="docs/images/green_apple.png" width="50%" />
</p>

### 3. Visual DNA Extraction

```bash
./nanobanana-cli --image apple.png --extract-dna --output "dna.json"
```

```json
{
  "style": "natural food photography, realistic",
  "scene": "rustic indoor kitchen counter",
  "subject": "single red apple, highly glossy skin",
  "camera": "close-up shot, shallow depth of field",
  "lighting": "soft natural daylight, window light",
  "materials": "polished apple skin, rough wood grain",
  "colors": "deep red, forest green, warm brown wood tones"
}
```

### 4. DNA-Driven Generation

```bash
./nanobanana-cli --prompt "a bright golden yellow apple" --visual-dna dna.json --output "yellow_apple.png"
```

<p align="center">
  <img src="docs/images/yellow_apple_from_dna.png" width="50%" />
</p>

### 5. Image Description

```bash
./nanobanana-cli --image photo.jpg --describe --output "description.txt"
```

## Prompting Best Practices

### The Creative Brief Formula

```
[Subject] + [Action/Pose] + [Environment] + [Lighting/Camera] + [Style/Mood] + [Technical Specs]
```

**Example:**
> "A 1967 cherry-red Mustang fastback, parked on a wet cobblestone street in London at night, golden hour backlighting, cinematic teal and orange grading, 85mm lens, f/2.8"

### Pro Visual Lexicon

| Category | Keywords |
|----------|----------|
| **Lighting** | Golden hour backlighting, Volumetric fog, Rembrandt lighting, Chiaroscuro |
| **Lenses** | 85mm f/1.8 (portrait), Macro lens, 24mm wide angle, Tilt-shift |
| **Materials** | Brushed aluminum, Subsurface scattering, Weathered leather, Wet concrete |
| **Styles** | Film grain, Cinematic color grading, Watercolor wash, Isometric 3D |

### Bundled DNA Templates

Pre-configured styles in `assets/templates/`:

| Template | Aesthetic |
|----------|-----------|
| `cinematic_fujifilm.json` | Film-like, golden hour, warm tones, film grain |
| `blueprint_3d.json` | Technical blueprint, orthographic projection, line art |

## Technical Specifications

| Feature | Values |
|---------|--------|
| **Aspect Ratios** | `1:1` `4:3` `3:4` `3:2` `2:3` `16:9` `9:16` `21:9` `4:5` `5:4` `1:4` `4:1` `1:8` `8:1` |
| **Resolutions** | `0.5K` (512px) · `1K` (default) · `2K` · `4K` (4096px) |
| **Thinking Levels** | `minimal` (fast) · `high` (best adherence) |
| **Providers** | Gemini API (AI Studio) · Vertex AI (Google Cloud) |
| **Input Formats** | PNG, JPEG, WebP |
| **Max Images** | Up to 14 input images per request |

## Authentication

**Gemini API (recommended):**

```bash
export GEMINI_API_KEY="your_key"
```

Get a free key at [Google AI Studio](https://aistudio.google.com/apikey).

**Vertex AI (Google Cloud):**

```bash
export GOOGLE_CLOUD_PROJECT="your_project"
export GCP_ACCESS_TOKEN=$(gcloud auth print-access-token)
./nanobanana-cli --provider vertex ...
```

## CLI Reference

```
nanobanana-cli [OPTIONS]

OPTIONS:
  -p, --prompt <TEXT>          Text description for generation/editing
  -s, --style <TEXT>           Artistic style instruction
  -i, --image <FILE>           Input image(s), up to 14 (repeatable)
  -o, --output <FILE>          Output file path [default: output.png]
      --extract-dna            Extract visual DNA as JSON
      --describe               Generate text description of image(s)
      --visual-dna <JSON|FILE> Visual DNA JSON string or file path
      --provider <PROVIDER>    API provider: gemini or vertex [default: gemini]
      --aspect-ratio <RATIO>   Aspect ratio [default: 1:1]
      --image-size <SIZE>      Resolution tier [default: 1K]
      --thinking-level <LEVEL> Reasoning depth [default: high]
  -h, --help                   Print help
  -V, --version                Print version
```

## Related

- **[nanobanana2-mcpb](https://github.com/OhJayGee/nanobanana2-mcpb)** — One-click Claude Desktop extension with the same capabilities (no CLI needed)

## License

[MIT](LICENSE) — Copyright 2026 OhJayGee