Install & Configure

The Gunni CLI lets you generate, edit, and transform media from your terminal. All operations go through the Gunni API server, so you only need your API key.

Install

# Use directly (no install)
npx gunni

# Or install globally
npm install -g gunni

Configure

Set your API key once. All subsequent commands authenticate automatically.

gunni config --set-gunni-key YOUR_KEY

Verify

gunni list models

If you see the model list, you are connected and ready to go.

image

Unified image command. The CLI auto-routes based on what you provide: text only generates, image + text edits, image only describes, image + --upscale upscales, image + --remove-bg removes the background.

Usage

gunni image [image_path] [prompt] [flags]

Examples

# Generate from text
gunni image "a fox in watercolor style" -o output.png

# Edit an image with a prompt
gunni image photo.jpg "make it warmer and more cinematic" -o edited.png

# Describe an image
gunni image photo.jpg

# Upscale an image
gunni image photo.jpg --upscale -o upscaled.png
gunni image photo.jpg --upscale --scale 4 -o upscaled-4x.png

# Remove background
gunni image photo.jpg --remove-bg -o clean.png

# Generate multiple variants
gunni image "product shot on white" --variants 4

Flags

Default models

video

Generate video from a still image (image-to-video) or a text prompt (text-to-video). The CLI auto-selects the correct model variant based on input.

Usage

gunni video [image_path] [prompt] [flags]

Examples

# Image to video
gunni video photo.jpg "slow zoom out" -o video.mp4

# Text to video
gunni video "ocean waves at sunset, golden hour" -o video.mp4

# Specify model and duration
gunni video photo.jpg "pan left" -m veo-3.1 --duration 10 -o video.mp4

Flags

Default models

audio

Convert text to natural-sounding speech.

Usage

gunni audio "text to speak" [flags]

Examples

gunni audio "Welcome to Gunni" -o speech.mp3
gunni audio "Breaking news: AI can now talk" -m elevenlabs-tts -o news.mp3

Flags

lipsync

Lip synchronization: sync audio onto a video, or generate a talking avatar from a single image plus audio.

Usage

gunni lipsync <audio> [flags]

Examples

# Lip sync: video + audio
gunni lipsync narration.mp3 -v speaker.mp4 -o synced.mp4

# Avatar: image + audio
gunni lipsync narration.mp3 -i headshot.jpg --model kling-avatar -o avatar.mp4

Flags

Modes

learn

Access the Gunni creative knowledge base. Browse topics on prompting technique, brand design, UI mockups, advertising, product photography, video production, and more.

Usage

gunni learn [topic]

Available topics

models

List all available models and their capabilities.

Usage

gunni list models [--type category]

Examples

# List all models
gunni list models

# Filter by category
gunni list models --type video
gunni list models --type image

config

Manage CLI configuration. Set your API key and view current settings.

Usage

gunni config [flags]

Flags

history

Search and browse your past generations.

Usage

gunni history [query]

Examples

# Browse recent generations
gunni history

# Search by prompt text
gunni history "fox watercolor"

style

CRUD operations for visual styles. Styles encapsulate a visual direction (description, negative prompts, model preferences, reference images) that can be applied to any generation with --style.

Usage

gunni style list
gunni style get <name>
gunni style create <name> [flags]
gunni style delete <name>

preset

CRUD operations for production presets. Presets define platform-specific output settings (aspect ratio, framing rules, prompt suffixes) for consistent delivery across platforms like Instagram, TikTok, or web.

Usage

gunni preset list
gunni preset get <name>
gunni preset create <name> [flags]
gunni preset delete <name>

template

CRUD operations for prompt templates. Templates are reusable prompt structures with variables, letting you standardize prompts across a team or project.

Usage

gunni template list
gunni template get <name>
gunni template create <name> [flags]
gunni template delete <name>

pipeline

CRUD operations for multi-step workflows. Pipelines define a sequence of generation steps that execute in order, passing outputs forward.

Usage

gunni pipeline list
gunni pipeline get <name>
gunni pipeline create <name> [flags]
gunni pipeline delete <name>

ref

Reference asset management. Save, organize, and retrieve reference images by name and collection.

Usage

gunni ref list
gunni ref get <name>
gunni ref save <url> --name <name> [--collection <collection>]
gunni ref delete <name>

research

Visual search. Find reference images and inspiration for a given query.

Usage

gunni research "query" [--num count]

Examples

# Default: 6 results
gunni research "minimalist packaging design"

# More results
gunni research "retro poster art" --num 15

Chaining Workflows

The output of one Gunni operation becomes the input to the next. Chain steps to build complete production workflows without leaving the terminal.

Example: product image pipeline

Generate a product shot, remove the background, composite into a new scene, then upscale for print:

# Step 1: Generate product shot
gunni image "sneaker on clean surface" -o product.png

# Step 2: Remove background
gunni image product.png --remove-bg -o clean.png

# Step 3: Composite into new scene
gunni image clean.png "place on rainy city street" -o scene.png

# Step 4: Upscale to 4x for print
gunni image scene.png --upscale --scale 4 -o final.png

Each command reads the previous output file and passes it through the next operation. This works because Gunni auto-routes based on the combination of inputs and flags.

Global Flags

These flags work on any command.