Command Line Interface (CLI)

Terminal-native AI image generation backed by Go Bananas!'s multi-provider model registry — Google Gemini (Nano Banana 2 Lite, Nano Banana 2, Go Bananas! Pro) and OpenAI (GPT Image 2, GPT Image 2.5 Flare and Sunburst), picked per request.

Overview

Go Bananas CLI brings professional AI image generation directly to your terminal. Built for developers, designers, and power users who live in the command line, it delivers the full capabilities of Go Bananas through a streamlined interface.

Key Features

Dual Transport — Automatically switches between MCP protocol and REST API
Session Persistence — Maintains editing sessions across commands
Local Downloads — Save images directly to disk
Scriptable — Perfect for automation and CI/CD pipelines
Core Tool Access — Generate/edit images and manage libraries from the terminal

Installation

Global Install (Recommended)

Install once, use everywhere:

bash

npm install -g gobananas-cli

Verify installation:

bash

gobananas --version
# or use the shorthand:
gb --version

No-Install Mode

Try it instantly with npx:

bash

npx gobananas-cli generate "sunset over mountains"

Requirements

Node.js: v20.3.0 or higher
Account: a Go Bananas account (sign up). Sign in with gb auth login, or use an API key

The CLI and gobananas-mcp proxy negotiate MCP 2026-07-28 with modern HTTP servers and fall back to legacy MCP automatically. Existing stdio client configuration does not need to change.

Quick Start

bash

gb auth login

This opens Go Bananas in your browser, asks you to approve access, and saves the sign-in locally. Use --no-open to print the link instead of opening a browser. Check it with gb auth status and remove it with gb auth logout.

For scripts and CI, use an API key instead:

bash

gb config set apiKey sk_live_your_api_key_here

Your credentials are stored locally. gb auth status shows which ones are configured.

2. Generate Your First Image

bash

gb generate "a photorealistic sunset over mountains"
# or use the shorthand:
gb gen "a photorealistic sunset over mountains"

3. Continue Editing

Edit your last image without specifying an ID:

bash

gb continue "add dramatic clouds"
# or:
gb cont "add dramatic clouds"

4. Download Images

bash

gb gen "mountain landscape" --download
# or specify a path:
gb gen "mountain landscape" --download ./my-image.png

Command Reference

Core Commands

Command	Aliases	Description
`generate`	`gen`, `g`	Generate images from text prompts
`edit`	`e`	Edit a specific image by ID
`continue`	`cont`, `c`	Continue editing the last image
`upload`	`up`	Upload an image from URL for editing

Library Management

Command	Aliases	Description
`char`	`character`	Manage character library
`prod`	`product`	Manage product references
`style`	`preset`	Manage style presets

Analytics & Information

Command	Aliases	Description
`session`	`sess`	View session history
`usage`	`stats`	View usage statistics
`search`	`find`	Search image gallery
`image`	`img`	Get image info by ID
`account`	`acc`	View account summary

Configuration

Command	Aliases	Description
`config`	`cfg`	Manage CLI configuration
`auth`	—	Browser sign-in: `login`, `status`, `logout`
`subscription`	—	ChatGPT subscription: `status`, `open`
`info`	—	Show CLI status
`mcp-help`	—	Get help on MCP tools
`mcp`	—	Run the MCP STDIO proxy (same as `npx gobananas-mcp`)

Generate Command

Generate new images from text prompts.

Usage

bash

gb generate <prompt> [options]

Options

Option	Description
`-n, --count <number>`	Number of images (1-4)
`-a, --aspect <ratio>`	Aspect ratio (square, portrait, landscape, 16:9, 9:16, 4:3, 3:4)
`--negative <prompt>`	What to avoid in the image
`--style <instruction>`	Style instruction for the model
`--style-preset <name>`	Use a saved style preset
`--model <id>`	Model (gemini-flash-lite-image, gemini-flash-image, gemini-pro-image, openai-gpt-image-2, openai-gpt-image-2.5-flare, openai-gpt-image-2.5-sunburst)
`-d, --download`	Download to local disk
`-o, --output <path>`	Output path for download
`--json`	Output raw JSON

Examples

bash

# Basic generation
gb gen "a serene mountain lake at dawn"

# With aspect ratio
gb gen "hero banner for website" --aspect 16:9

# With negative prompt
gb gen "portrait photo" --negative "blurry, low quality"

# Using style preset
gb gen "forest landscape" --style-preset "Watercolor"

# Download with custom path
gb gen "logo design" --download ./assets/logo.png

Edit Commands

Edit by ID

Edit a specific image by its database ID:

bash

gb edit <image-id> <prompt>

Example:

bash

gb edit 42 "add a sunset sky"

Continue Editing

Edit the last image in your session:

bash

gb continue <prompt>
# or:
gb cont <prompt>

Example:

bash

gb gen "mountain landscape"
# → Creates image 42

gb cont "add snow on the peaks"
# → Edits image 42, creates 43

gb cont "make the sky more dramatic"
# → Edits image 43, creates 44

Upload and Edit

Upload an external image for editing:

bash

gb upload <url> <prompt>

Example:

bash

gb upload "https://example.com/photo.jpg" "convert to oil painting style"

Character Commands

Manage your character library for consistent multi-scene generation.

Create Character

bash

gb char create <name> [options]

Options:

Option	Description
`-p, --base-prompt <prompt>`	Character description
`-r, --reference-images <ids>`	Comma-separated image IDs
`-d, --description <text>`	Internal notes

Example:

bash

# First, generate a character design
gb gen "friendly robot mascot, chrome finish, LED eyes" --download

# Save it as a character (using the image ID from above)
gb char create "RoboBot" \
  --base-prompt "friendly robot mascot with chrome finish and LED eyes" \
  --reference-images 42 \
  --description "Company mascot"

Generate with Character

bash

gb char generate <name> --scene <prompt>

Example:

bash

gb char generate "RoboBot" --scene "waving hello in an office"
gb char generate "RoboBot" --scene "flying through space"
gb char generate "RoboBot" --scene "celebrating with confetti"

List Characters

bash

gb char list

Get Character Details

bash

gb char get <name>

Update Character

bash

gb char update <name> [options]

Delete Character

bash

gb char delete <name>

Product Commands

Manage product references for marketing image generation.

Create Product Reference

bash

gb prod create <name> --url <image-url> [options]

Options:

Option	Description
`-u, --url <url>`	Product image URL (required)
`-d, --description <text>`	Product description
`-t, --tags <tags>`	Comma-separated tags

Example:

bash

gb prod create "Chrome Arrow Decor" \
  --url "https://example.com/chrome-arrow.jpg" \
  --description "Sleek chrome arrow wall decoration" \
  --tags "home-decor,chrome,wall-art"

Generate with Product

bash

gb prod generate <name> --scene <prompt> [options]

Options:

Option	Description
`-s, --scene <prompt>`	Scene description (required)
`-a, --additional <details>`	Additional styling details
`-d, --download`	Download the result

Example:

bash

gb prod generate "Chrome Arrow Decor" \
  --scene "on a wooden desk with laptop and coffee" \
  --additional "warm lighting, professional photography" \
  --download

List Products

bash

gb prod list [--search <query>]

Get Product Details

bash

gb prod get <name>

Delete Product

bash

gb prod delete <name>

Style Preset Commands

Create reusable style templates for consistent branding.

Create Style Preset

bash

gb style create <name> [options]

Options:

Option	Description
`-p, --prompt <text>`	Style prompt (prepended to all generations)
`-n, --negative <text>`	Default negative prompt
`-i, --instruction <text>`	System instruction
`-a, --aspect <ratio>`	Default aspect ratio

Example:

bash

gb style create "Watercolor Brand" \
  --prompt "watercolor painting style, soft edges, pastel colors" \
  --negative "photorealistic, 3D render, harsh lines" \
  --aspect 16:9

Use Style Preset

bash

gb gen "mountain landscape" --style-preset "Watercolor Brand"

List Style Presets

bash

gb style list

Update Style Preset

bash

gb style update <name> [options]

Delete Style Preset

bash

gb style delete <name>

Search & Analytics

Search Images

bash

gb search [options]

Options:

Option	Description
`-q, --query <text>`	Search prompt text
`--from <date>`	Start date (ISO format)
`--to <date>`	End date
`-l, --limit <number>`	Results limit

Example:

bash

gb search --query "sunset" --from 2025-01-01 --limit 10

View Usage Statistics

bash

gb usage stats [options]

Options:

Option	Description
`--from <date>`	Start date
`--to <date>`	End date
`-g, --granularity <level>`	hour, day, or week

Example:

bash

gb usage stats --from 2025-01-01 --granularity day

View Account Summary

bash

gb account summary

Shows:

Total images generated
Storage used
Character library size
Product references count
Recent activity

View Session History

bash

gb session list
gb session view <session-id>

Configuration

View Current Config

bash

gb config show

Set Configuration Values

bash

gb config set <key> <value>

Available Settings:

Key	Description	Default
`serverUrl`	API endpoint	`https://gobananasai.com`
`apiKey`	Your API key	—
`transport`	Transport mode	`auto`
`outputDir`	Download directory	`./generated`
`defaultAspectRatio`	Default aspect ratio	`square`

Examples:

bash

gb config set serverUrl https://gobananasai.com
gb config set transport rest  # Force REST API
gb config set outputDir ./images

Transport Modes

Mode	Description
`auto`	Automatically choose best transport (default)
`mcp`	Force MCP protocol
`rest`	Force REST API

Reset Configuration

bash

gb config reset

View Config File Path

bash

gb config path

Global Options

Available on all commands:

Option	Description
`--json`	Output as JSON (for scripting)
`-v, --verbose`	Show detailed logs
`--help`	Show command help
`--version`	Show CLI version

Scripting & Automation

The CLI is designed for automation. Use --json for machine-readable output:

bash

#!/bin/bash
# Generate product images for catalog

products=("Widget A" "Widget B" "Widget C")

for product in "${products[@]}"; do
  result=$(gb prod generate "$product" \
    --scene "professional product shot, white background" \
    --json)

  url=$(echo "$result" | jq -r '.fullUrl')
  echo "Generated: $url"
done

CI/CD Integration

yaml

# GitHub Actions example
- name: Generate Marketing Images
  run: |
    npm install -g gobananas-cli
    gb config set apiKey ${{ secrets.GO_BANANAS_API_KEY }}
    gb prod generate "Product" --scene "hero shot" --download ./dist/hero.png

MCP Proxy

gobananas-mcp (or gb mcp) is a local STDIO proxy for MCP clients that need a command rather than a URL. It forwards every tool call to Go Bananas.

json

{
  "mcpServers": {
    "go-bananas": {
      "command": "npx",
      "args": ["-y", "gobananas-mcp"],
      "env": {
        "GO_BANANAS_SERVER_URL": "https://gobananasai.com",
        "GO_BANANAS_MCP_TRANSPORT": "streamable-http"
      }
    }
  }
}

It uses your gb auth login sign-in, or GO_BANANAS_API_KEY when set.

Timeouts

Stage	Limit
Connecting to Go Bananas	30 seconds
A single tool call	15 minutes (covers waiting in the generation queue plus generation)

Since 1.3.5, the proxy reads your browser sign-in for every request and refreshes it when Go Bananas answers 401, so a long session no longer fails a call with "Access token has expired".
Since 1.3.6, when Go Bananas rejects the sign-in the proxy says the tool did not run and is safe to retry. Run gb auth login again (or check your API key), then retry.
Other failures are different: if a call times out or its response is lost, the tool may already have finished. Check your gallery before retrying; the proxy never replays a call on its own.

MCP proxy diagnostics

The proxy adds one tool of its own, go_bananas_diagnose, so clients using it see 54 tools instead of 53. Ask your agent to run it when tools are missing or calls fail. It takes no parameters, runs no generation, and reports:

proxy package and version, server URL and transport
how it is signed in (browser sign-in or API key, with the key masked)
whether it is connected and how many tools it has cached, plus the last connection error

If the proxy was disconnected, running it also tries to reconnect. When that fails it suggests fixes: run gb auth login, set GO_BANANAS_API_KEY, check the server is reachable, or set GO_BANANAS_MCP_TRANSPORT.

Troubleshooting

API Key Issues

bash

# Check if key is configured
gb info

# Re-set your key
gb config set apiKey sk_live_your_key

Connection Issues

bash

# Force REST API if MCP fails
gb config set transport rest

# Check server URL
gb config show

Session Issues

bash

# View current session
gb session list

# Start fresh session
gb config set sessionId ""

Examples Gallery

Portrait Photography

bash

gb gen "professional headshot, studio lighting, neutral background" \
  --aspect portrait \
  --style "high-end photography, sharp focus"

Logo Design

bash

gb gen "minimalist tech startup logo, abstract geometric shapes" \
  --aspect 1:1 \
  --negative "text, words, letters"

bash

gb gen "inspirational quote background, gradient colors, modern" \
  --aspect 9:16 \
  --download ./instagram-story.png

Product Mockups

bash

gb prod create "App Icon" --url "https://example.com/icon.png"
gb prod generate "App Icon" \
  --scene "displayed on iPhone screen, desk setup" \
  --additional "professional photography, shallow depth of field"

Character Animation Frames

bash

gb char create "Mascot" --base-prompt "cute owl character" --reference-images 42

for pose in "waving" "jumping" "sleeping" "eating"; do
  gb char generate "Mascot" --scene "$pose" --download "./frames/$pose.png"
done

Next Steps

Authentication Guide — API key management
Character Reference Guide — Deep dive into character system
Product Marketing Guide — E-commerce workflows
REST API Reference — Direct API integration

Command Line Interface (CLI) ​

Overview ​

Key Features ​

Installation ​

Global Install (Recommended) ​

No-Install Mode ​

Requirements ​

Quick Start ​

1. Sign In ​

2. Generate Your First Image ​

3. Continue Editing ​

4. Download Images ​

Command Reference ​

Core Commands ​

Library Management ​

Analytics & Information ​

Configuration ​

Generate Command ​

Usage ​

Options ​

Examples ​

Edit Commands ​

Edit by ID ​

Continue Editing ​

Upload and Edit ​

Character Commands ​

Create Character ​

Generate with Character ​

List Characters ​

Get Character Details ​

Update Character ​

Delete Character ​

Product Commands ​

Create Product Reference ​

Generate with Product ​

List Products ​

Get Product Details ​

Delete Product ​

Style Preset Commands ​

Create Style Preset ​

Use Style Preset ​

List Style Presets ​

Update Style Preset ​

Delete Style Preset ​

Search & Analytics ​

Search Images ​

View Usage Statistics ​

View Account Summary ​

View Session History ​

Configuration ​

View Current Config ​

Set Configuration Values ​

Transport Modes ​

Reset Configuration ​

View Config File Path ​

Global Options ​

Scripting & Automation ​

CI/CD Integration ​

MCP Proxy ​

Timeouts ​

Sign-in and retries ​

MCP proxy diagnostics ​

Troubleshooting ​

API Key Issues ​

Connection Issues ​

Session Issues ​

Examples Gallery ​

Portrait Photography ​

Logo Design ​

Social Media Content ​

Product Mockups ​

Character Animation Frames ​

Next Steps ​

Command Line Interface (CLI)

Overview

Key Features

Installation

Global Install (Recommended)

No-Install Mode

Requirements

Quick Start

1. Sign In

2. Generate Your First Image

3. Continue Editing

4. Download Images

Command Reference

Core Commands

Library Management

Analytics & Information

Configuration

Generate Command

Usage

Options

Examples

Edit Commands

Edit by ID

Continue Editing

Upload and Edit

Character Commands

Create Character

Generate with Character

List Characters

Get Character Details

Update Character

Delete Character

Product Commands

Create Product Reference

Generate with Product

List Products

Get Product Details

Delete Product

Style Preset Commands

Create Style Preset

Use Style Preset

List Style Presets

Update Style Preset

Delete Style Preset

Search & Analytics

Search Images

View Usage Statistics

View Account Summary

View Session History

Configuration

View Current Config

Set Configuration Values

Transport Modes

Reset Configuration

View Config File Path

Global Options

Scripting & Automation

CI/CD Integration

MCP Proxy

Timeouts

Sign-in and retries

MCP proxy diagnostics

Troubleshooting

API Key Issues

Connection Issues

Session Issues

Examples Gallery

Portrait Photography

Logo Design

Social Media Content

Product Mockups

Character Animation Frames

Next Steps