AI image generation from the terminal
CLI, interactive TUI, and MCP server for AI agents — powered by the Pixelmuse API. One install, any model, predictable pricing.
npm install -g pixelmuseQuick Start
Install globally
npm install -g pixelmuseAuthenticate with your API key
pixelmuse loginGenerate your first image
pixelmuse "a cat floating through space"Requires Node.js 20+. For terminal image previews, install chafa (brew install chafa).
Four Interfaces, One API
Pick the one that fits your workflow. They all use the same API key and credit balance.
CLI
Generate images from any terminal. Pipe from stdin, JSON output for scripting, watch mode for iteration.
pixelmuse "a cyberpunk city at night" -m recraft-v4 -a 16:9Interactive TUI
Full terminal UI with model browser, generation wizard, gallery, and account management.
pixelmuse uiMCP Server
Let AI agents in Claude Code, Cursor, and Windsurf generate images autonomously.
{ "pixelmuse": { "command": "npx", "args": ["-y", "pixelmuse-mcp"] } }Claude Code Skill
A prompt template that auto-triggers when you ask Claude to generate images mid-conversation.
"generate a blog thumbnail for my React hooks post"CLI Reference
All commands and flags at a glance.
Commands
| Command | Description |
|---|---|
pixelmuse "prompt" | Generate an image (default command) |
pixelmuse models | List available models with credit costs |
pixelmuse account | Account balance and usage stats |
pixelmuse history | Recent generations in a table |
pixelmuse open <id> | Open a generation in system viewer |
pixelmuse login | Authenticate with your API key |
pixelmuse logout | Remove stored credentials |
pixelmuse template <cmd> | Manage prompt templates (init/use/list) |
pixelmuse ui | Launch the interactive TUI |
Flags
| Flag | Description |
|---|---|
-m, --model | Model ID |
-a, --aspect-ratio | Aspect ratio |
-s, --style | Style preset |
-o, --output | Output file path |
--json | Machine-readable JSON output |
--no-preview | Skip terminal image preview |
--open | Open result in system viewer |
--clipboard | Copy image to clipboard |
--watch <file> | Regenerate when file changes |
--no-save | Don't save image to disk |
MCP Server Setup
Give your AI agent the power to generate images. Add this to your editor config.
Add to ~/.claude/.mcp.json
{
"mcpServers": {
"pixelmuse": {
"command": "npx",
"args": ["-y", "pixelmuse-mcp"],
"env": {
"PIXELMUSE_API_KEY": "pm_live_your_key_here"
}
}
}
}| Tool | Description |
|---|---|
generate_image | Generate an image with model, aspect ratio, style, and output path |
list_models | List all available models with credit costs |
check_balance | Check your credit balance and plan info |
Prompt Templates
Save reusable prompts as YAML files with variables and default settings.
# Scaffold a new template
pixelmuse template init product-shot
# Generate with a template
pixelmuse template use blog-thumbnail --var subject="React hooks guide"
# List all templates
pixelmuse template listTemplate format (~/.config/pixelmuse-cli/prompts/)
name: Blog Thumbnail
description: Dark-themed blog post thumbnail
prompt: >
A cinematic {{subject}} on a dark gradient background,
dramatic lighting, 8K resolution
defaults:
model: nano-banana-2
aspect_ratio: "16:9"
variables:
subject: "code editor with syntax highlighting"
tags: [blog, thumbnail, dark]Models
Switch models with -m model-id. All models available on every plan.
| Model | Credits |
|---|---|
nano-banana-2defaultSpeed, text rendering, world knowledge | 1 |
nano-banana-proText rendering, real-time info, multi-image editing | 4 |
flux-schnellQuick mockups, ideation | 1 |
imagen-3Realistic photos, complex compositions | 1 |
recraft-v4Typography, design, composition | 1 |
recraft-v4-proHigh-res design, art direction | 7 |
Start Building
Everything you need to integrate AI image generation into your workflow.
