yummycli

繁體中文 | 简体中文 | English

An AI-friendly CLI for multimodal model providers — built for humans and AI Agents.

Supports image generation and editing, and video generation via Gemini, with more providers (Claude, OpenAI, Qwen) planned.

Install · Auth · Image Generation · Video Generation · Agent Skills · Commands

Why yummycli?

• Agent-Native Design — Structured Skills out of the box, designed so AI Agents can call image and video APIs with zero extra setup
• Capability-First Architecture — image generate and video generate are the stable automation contracts; gemini nanobanana and gemini veo are human-friendly shortcuts on top
• Structured JSON Output — Every command writes JSON to stdout, making it trivial to pipe into agents, scripts, or other tools
• Secure Credential Storage — API keys stored in the OS-native keychain (macOS Keychain, Linux Secret Service), never in plain text
• Provider-Agnostic — One CLI surface across providers; add a new provider without changing your scripts

Installation

Requirements

• Node.js 16+ with npm
• Go 1.23+ and make (only required when building from source)

From npm (recommended)

# Install CLI
npm install -g @yummysource/yummycli

# Install Agent Skills (required for AI Agent usage)
npx skills add yummysource/yummycli -y -g

Verify the install:

yummycli version

From source

git clone https://github.com/yummysource/yummycli.git
cd yummycli
make install

# Install Agent Skills (required for AI Agent usage)
npx skills add yummysource/yummycli -y -g

Authentication

yummycli stores API keys per provider in the OS keychain. You only need to do this once per provider.

Commands

Examples

# Save a Gemini API key
yummycli auth init --provider gemini --api-key "AIza..."

# Check if Gemini is configured (shows masked key preview)
yummycli auth status --provider gemini

# Remove Gemini credentials
yummycli auth remove --provider gemini

Output from auth init:

{"provider":"gemini","configured":true}

Output from auth list:

[{"provider":"gemini","configured":true,"apiKeyPreview":"AIza...xxxx"}]

Output from auth status:

{"provider":"gemini","configured":true,"apiKeyPreview":"AIza...xxxx"}

Gemini shortcut

gemini init is a provider-scoped alias for auth init --provider gemini:

yummycli gemini init --api-key "AIza..."

Image Generation

yummycli supports two equivalent entry points for image generation:

Both call the same underlying implementation. Use whichever fits your context.

Quick start

# Step 1: configure Gemini credentials (one-time)
yummycli gemini init --api-key "AIza..."

# Step 2: generate an image from a text prompt
yummycli gemini nanobanana --prompt "A ripe banana on a white plate, studio lighting"

The generated image is saved to the current directory with an auto-generated filename:

gemini_20260410123456_789.png

Flags

For image generate, also pass --provider gemini (required). The same Gemini defaults apply — --model, --aspect-ratio, and --image-size are filled in automatically when omitted.

Text-to-image generation

yummycli gemini nanobanana \
  --prompt "A cyberpunk cityscape at night, neon reflections on wet streets"

# Specify output path and resolution
yummycli gemini nanobanana \
  --prompt "A minimalist logo, flat design, white background" \
  --output logo.png \
  --image-size 4K

Image editing

Pass one or more reference images with --input-image:

# Single-image edit
yummycli gemini nanobanana \
  --prompt "Turn this into a watercolor illustration" \
  --input-image ./photo.png

# Multi-image reference
yummycli gemini nanobanana \
  --prompt "Blend these two references into a single polished poster" \
  --input-image ./subject.png \
  --input-image ./background.jpg

Supported input formats: .png, .jpg / .jpeg, .webp.

Aspect ratio

# Vertical — phone wallpaper, story format
yummycli gemini nanobanana --prompt "..." --aspect-ratio 9:16

# Square — social avatar, icon
yummycli gemini nanobanana --prompt "..." --aspect-ratio 1:1

# Widescreen — desktop wallpaper, presentation banner
yummycli gemini nanobanana --prompt "..." --aspect-ratio 21:9

Model selection

# Flash (default) — faster, supports more aspect ratios and smaller sizes
yummycli gemini nanobanana --prompt "..." --model gemini-3.1-flash-image-preview

# Pro — higher quality, fewer size/ratio options
yummycli gemini nanobanana --prompt "..." --model gemini-3-pro-image-preview

Model compatibility

Aspect ratio

1:4, 1:8, 4:1, 8:1 are Flash-only and not supported by the Pro model.

Image size

512 and 0.5K are Flash-only. Size values are case-insensitive (4k and 4K both work).

JSON output

Every successful generation writes a result to stdout:

{
  "provider": "gemini",
  "output": "gemini_20260410123456_789.png",
  "model": "gemini-3.1-flash-image-preview",
  "inputImageCount": 0
}

Use the output field to locate the generated file.

Using image generate directly

image generate is the provider-agnostic stable API. It accepts the same flags but requires an explicit --provider:

yummycli image generate \
  --provider gemini \
  --prompt "A serene mountain lake at sunrise" \
  --aspect-ratio 16:9 \
  --image-size 2K \
  --output landscape.png

This form is recommended for scripts and AI Agents — it will continue to work unchanged as new providers are added.

Video Generation

yummycli supports video generation via Google Veo, with two equivalent entry points:

Quick start

# Step 1: configure Gemini credentials (one-time)
yummycli gemini init --api-key "AIza..."

# Step 2: generate a video from a text prompt
yummycli gemini veo --prompt "A golden retriever puppy chasing a red ball in a sunny park"

The generated video is saved to the current directory with an auto-generated filename:

veo_20260417_142301_047.mp4

Flags

Generation modes

--input-image can be repeated; the count determines the generation mode automatically:

# Text-to-video
yummycli gemini veo --prompt "Timelapse of clouds moving over mountain peaks"

# Image-to-video (animate a still image)
yummycli gemini veo \
  --prompt "The dog starts running toward the camera" \
  --input-image ./dog.jpg

# Reference-guided (two images)
yummycli gemini veo \
  --prompt "Combine the character with this background environment" \
  --input-image ./character.png \
  --input-image ./background.jpg

Model compatibility

Duration accepts only discrete values:

Resolution support per model:

Constraints: 1080p and 4k require --duration 8. 4k requires a veo-3.1 model.

JSON output

{
  "provider": "gemini",
  "output": "veo_20260417_142301_047.mp4",
  "model": "veo-3.1-fast-generate-preview",
  "duration_seconds": 8,
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "elapsed_seconds": 73
}

Agent Skills

yummycli ships with Skills — structured instruction files that teach AI Agents how to use the CLI correctly.

Skills are located in ./skills/.

Installation

npx skills add yummysource/yummycli -y -g

Load yummy-shared before any other yummycli skill.

Command Reference

yummycli
├── version                              Show the yummycli version
│
├── auth
│   ├── init    --provider  --api-key    Save API key for a provider
│   ├── list                             List all providers and credential status
│   ├── status  --provider               Show credential status for a provider
│   └── remove  --provider               Delete stored credentials
│
├── gemini
│   ├── init  --api-key                  Initialize Gemini credentials
│   ├── nanobanana                       Generate / edit images with Gemini
│   │     --prompt        (required)
│   │     --output
│   │     --model
│   │     --aspect-ratio
│   │     --image-size
│   │     --input-image   (repeatable)
│   └── veo                              Generate videos with Gemini Veo
│         --prompt        (required)
│         --output
│         --model
│         --aspect-ratio
│         --duration
│         --resolution
│         --input-image   (repeatable, up to 3)
│
├── image
│   └── generate                         Provider-agnostic image generation
│         --provider      (required)
│         --prompt        (required)
│         --output
│         --model
│         --aspect-ratio
│         --image-size
│         --input-image   (repeatable)
│
└── video
    └── generate                         Provider-agnostic video generation
          --provider      (required)
          --prompt        (required)
          --output
          --model
          --aspect-ratio
          --duration
          --resolution
          --input-image   (repeatable, up to 3)

Contributing

Contributions are welcome. If you find a bug or have a feature request, open an Issue or Pull Request.

For significant changes, open an Issue first to discuss the approach.

License

MIT