Pixelmuse CLI Guide: AI Image Generation From Your Terminal

If you're a developer who lives in the terminal, you've probably hit this problem: you need an image for a blog post, a social card, or a project thumbnail — and suddenly you're context-switching to a browser, logging into some image generator, waiting for a result, downloading it, and dragging it into your project. That entire flow breaks your focus.

Pixelmuse CLI lets you generate AI images without leaving the terminal. One command, a prompt, and your image is saved to disk — ready to use. It also ships with an interactive TUI, prompt templates, and an MCP server so AI coding agents like Claude Code can generate images autonomously.

Sign up for Pixelmuse — 15 free credits to start generating.

Table of Contents

• Install Pixelmuse CLI
• Create Your Account
• Authenticate
• Generate Your First Image
• CLI Flags and Options
• Available Models
• Aspect Ratios
• Check Your Account and History
• Prompt Templates
• Interactive TUI
• MCP Server Setup
• Claude Code Skill
• Advanced Usage
• Quick Reference

Install Pixelmuse CLI

Requirements: Node.js 20+ and a package manager (pnpm, npm, or yarn).

# Install globally
pnpm add -g pixelmuse

# Or with npm
npm install -g pixelmuse

# Verify installation
pixelmuse --version

Optional: Install chafa for terminal image previews:

# macOS
brew install chafa

# Ubuntu/Debian
sudo apt-get install chafa

With chafa installed, Pixelmuse automatically renders a preview of your generated image right in the terminal.

Create Your Account

You need a Pixelmuse account to generate images. Every new account gets 15 free credits — enough for 15 generations with the default model.

Option 1: Sign up in the browser

Go to pixelmuse.studio/sign-up and create an account with email or GitHub.

Option 2: Sign up from the CLI

Run the setup wizard — it opens the signup page automatically if you don't have an account:

pixelmuse setup

The setup wizard walks you through account creation, authentication, MCP configuration, and default settings in one flow.

Authenticate

Pixelmuse CLI supports two authentication methods:

Device Code Login (Recommended)

pixelmuse login

This opens your browser to verify your device. Enter the code shown in your terminal, approve access, and you're authenticated. The API key is stored securely in your OS keychain.

Manual API Key

If you prefer, generate an API key at pixelmuse.studio/settings/api-keys and either:

# Set as environment variable (add to ~/.zshrc for persistence)
export PIXELMUSE_API_KEY="pm_live_your_key_here"

# Or enter manually during login
pixelmuse login
# Select "Enter API key manually" when prompted

Key resolution order: Environment variable → OS Keychain → Config file (~/.config/pixelmuse-cli/auth.json).

Generate Your First Image

The simplest generation — just a prompt:

pixelmuse "a cat floating through space"

That's it. Pixelmuse uses the default model (nano-banana-2, 1 credit), generates the image, saves it to your current directory, and shows a terminal preview.

The output file is named from your prompt: a-cat-floating-through-space.png.

With Options

# Widescreen blog thumbnail
pixelmuse "neon cityscape at night" -a 16:9

# Specific model and output path
pixelmuse "watercolor mountain landscape" -m imagen-3 -o hero.png

# Anime style
pixelmuse "samurai standing in rain" -s anime -a 2:3

CLI Flags and Options

Available Models

Pixelmuse ships with 6 models at different price points:

List models from the CLI anytime:

pixelmuse models

Start with nano-banana-2 — it's 1 credit, fast, and handles most use cases. Move to specialized models when you need specific strengths.

Aspect Ratios

# Blog thumbnail
pixelmuse "your prompt" -a 16:9

# Instagram story
pixelmuse "your prompt" -a 9:16

Check Your Account and History

# View credit balance and plan info
pixelmuse account

# See your last 20 generations
pixelmuse history

# Open a specific generation in your image viewer
pixelmuse open <generation-id>

Prompt Templates

Templates let you save reusable prompt configurations — prompt text, model, aspect ratio, and variables — as YAML files.

Create a Template

pixelmuse template init blog-thumbnail

This creates ~/.config/pixelmuse-cli/prompts/blog-thumbnail.yaml. Edit it:

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'
  style: none
variables:
  subject: 'code editor with syntax highlighting'
tags: [blog, thumbnail, dark]

Use a Template

# Generate with default variable values
pixelmuse template use blog-thumbnail

# Override variables
pixelmuse template use blog-thumbnail --var subject="React hooks diagram"

# List all templates
pixelmuse template list

# View template details
pixelmuse template show blog-thumbnail

Templates are powerful for batch content workflows — define your brand's image style once, then generate consistent visuals with one command.

Interactive TUI

For a more visual experience, launch the interactive terminal UI:

pixelmuse ui

The TUI gives you:

• Generation wizard — step-by-step image generation with model selection
• Gallery — browse all your past generations with previews
• Model browser — compare models side by side
• Account management — check credits, view usage stats
• Prompt editor — create and manage templates visually

Key bindings:

MCP Server Setup

The MCP (Model Context Protocol) server lets AI coding agents generate images autonomously. When you configure it, tools like Claude Code, Cursor, and Windsurf can call Pixelmuse directly during a conversation.

Get Your API Key

Go to pixelmuse.studio/settings/api-keys and copy your key.

Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "pixelmuse": {
      "command": "npx",
      "args": ["-y", "pixelmuse-mcp"],
      "env": {
        "PIXELMUSE_API_KEY": "pm_live_your_key_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (Settings → MCP):

{
  "pixelmuse": {
    "command": "npx",
    "args": ["-y", "pixelmuse-mcp"],
    "env": {
      "PIXELMUSE_API_KEY": "pm_live_your_key_here"
    }
  }
}

Windsurf

Same configuration as Cursor — add to your Windsurf MCP settings file.

What the MCP Server Provides

Three tools become available to your AI agent:

Once configured, you can ask Claude Code things like:

"Generate a 16:9 blog thumbnail showing a developer typing in a dark terminal"

And it will call Pixelmuse directly, save the image, and continue working — no context switch needed.

Auto-Configure via Setup

The setup wizard can detect and configure MCP for your editors automatically:

pixelmuse setup

It checks for Claude Code, Cursor, and Windsurf and offers to add the MCP configuration for you.

Claude Code Skill

If you use Claude Code, you can add a Pixelmuse skill that lets you generate images mid-conversation with natural language.

Create ~/.claude/skills/pixelmuse-generate/skill.md with the trigger phrases and instructions for Claude Code to call the Pixelmuse CLI. The skill enables prompts like:

"Generate a thumbnail for this blog post"

And Claude Code will run the appropriate pixelmuse command based on your context.

The Pixelmuse CLI README includes a ready-to-use skill template.

Advanced Usage

Piping Prompts

Read prompts from stdin — useful for scripting and chaining commands:

# From echo
echo "mountain landscape at golden hour" | pixelmuse -o landscape.png

# From a file
cat prompt.txt | pixelmuse -m imagen-3

# From another command
curl -s https://api.example.com/prompt | pixelmuse

Watch Mode

Auto-regenerate when a prompt file changes — great for iterating on prompts:

pixelmuse --watch prompt.txt -o output.png

Edit prompt.txt in your editor, save, and the image regenerates automatically.

JSON Output for Scripting

Get machine-readable output for automation pipelines:

pixelmuse --json "your prompt" | jq .output_path

Batch Generation with Shell Scripts

#!/bin/bash
prompts=("sunset over ocean" "mountain at dawn" "city at night")
for prompt in "${prompts[@]}"; do
  pixelmuse "$prompt" -a 16:9 -o "$(echo $prompt | tr ' ' '-').png"
done

Environment Variable Auth

For CI/CD or shared machines, set the API key as an environment variable:

export PIXELMUSE_API_KEY="pm_live_your_key_here"

This takes priority over keychain and config file auth.

Quick Reference

Get started at pixelmuse.studio/sign-up — 15 free credits, no credit card required. Full API documentation is at pixelmuse.studio/developers.