DEV Community

Cover image for Pixelmuse CLI Guide: AI Image Generation From Your Terminal
Starmorph AI
Starmorph AI

Posted on • Originally published at blog.starmorph.com on

Pixelmuse CLI Guide: AI Image Generation From Your Terminal

#pixelmuse #cli #aiimagegeneration #mcp

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.

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
Enter fullscreen mode Exit fullscreen mode

Optional: Install chafa for terminal image previews:

# macOS
brew install chafa

# Ubuntu/Debian
sudo apt-get install chafa
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

CLI Flags and Options

Flag Short Default Purpose
--model -m nano-banana-2 Model to use
--aspect-ratio -a 1:1 Image dimensions
--style -s none Style preset
--output -o Auto-named Output file path
--json — false Machine-readable JSON output
--no-preview — — Skip terminal preview
--open — false Open in system image viewer
--clipboard — false Copy image to clipboard
--watch — — Watch a prompt file, regenerate on save
--no-save — — Don't save to disk
--public — false Make image publicly visible

Available Models

Pixelmuse ships with 6 models at different price points:

Model Credits Best For
nano-banana-2 1 Speed, text rendering, world knowledge (default)
flux-schnell 1 Quick mockups and ideation
imagen-3 1 Photorealistic images, complex compositions
recraft-v4 1 Typography, graphic design, composition
nano-banana-pro 4 Advanced text rendering, multi-image editing
recraft-v4-pro 7 High-resolution design, art direction

List models from the CLI anytime:

pixelmuse models
Enter fullscreen mode Exit fullscreen mode

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

Ratio Use Case
1:1 Social media posts, avatars (default)
16:9 Blog thumbnails, YouTube thumbnails, OG images
9:16 Phone wallpapers, Instagram stories
4:3 Presentations
2:3 Portraits
21:9 Ultrawide banners 
# Blog thumbnail
pixelmuse "your prompt" -a 16:9

# Instagram story
pixelmuse "your prompt" -a 9:16
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

Key Action
Arrow keys Navigate
Enter Select
Esc Go back
q Quit

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"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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:

Tool Purpose
generate_image Generate an image with prompt, model, aspect ratio, style
list_models List available models and credit costs
check_balance Check account credit balance

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Watch Mode

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

pixelmuse --watch prompt.txt -o output.png
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

This takes priority over keychain and config file auth.

Quick Reference

Task Command
Install pnpm add -g pixelmuse
Setup wizard pixelmuse setup
Login pixelmuse login
Generate image pixelmuse "prompt"
Generate 16:9 pixelmuse "prompt" -a 16:9
Use specific model pixelmuse "prompt" -m imagen-3
Save to path pixelmuse "prompt" -o output.png
List models pixelmuse models
Check credits pixelmuse account
View history pixelmuse history
Launch TUI pixelmuse ui
Create template pixelmuse template init name
Use template pixelmuse template use name
Watch mode pixelmuse --watch file.txt
JSON output pixelmuse --json "prompt"

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

Originally published at StarBlog

Top comments (0)