llms.txt

# Pixelmuse CLI

> AI image generation from the terminal — CLI, TUI, and MCP server

Pixelmuse is a command-line tool for generating AI images. It supports multiple models (Flux, Imagen 3, Recraft V4, Nano Banana), offers a CLI, interactive TUI, and MCP server for AI agent integration.

## Quick Start

Install: `npm install -g pixelmuse`
Authenticate: `pixelmuse login`
Generate: `pixelmuse "a cat floating through space"`

## Links

- [Homepage](https://www.pixelmuse.studio)
- [Sign Up](https://www.pixelmuse.studio/sign-up)
- [API Documentation](https://www.pixelmuse.studio/developers)
- [API Keys](https://www.pixelmuse.studio/settings/api-keys)
- [Get Credits](https://www.pixelmuse.studio/get-credits)
- [GitHub Repository](https://github.com/starmorph/pixelmuse-cli)
- [npm Package](https://www.npmjs.com/package/pixelmuse)

## CLI Commands

- `pixelmuse "prompt"` — Generate an image (default command)
- `pixelmuse models` — List available models with credit costs
- `pixelmuse account` — View account balance and usage stats
- `pixelmuse history` — View recent generations
- `pixelmuse open <id>` — Open a generation in system viewer
- `pixelmuse login` — Authenticate with API key
- `pixelmuse logout` — Remove stored credentials
- `pixelmuse template <list|show|init|use>` — Manage reusable prompt templates
- `pixelmuse ui` — Launch interactive terminal UI

## CLI Flags

- `-m, --model` — Model ID (default: nano-banana-2)
- `-a, --aspect-ratio` — Aspect ratio (default: 1:1)
- `-s, --style` — realistic, anime, artistic, none
- `-o, --output` — Output file path
- `--json` — Machine-readable JSON output
- `--watch <file>` — Watch prompt file, regenerate on save
- `--clipboard` — Copy image to clipboard
- `--open` — Open result in system viewer

## Available Models

- `nano-banana-2` — 1 credit, speed and text rendering (default)
- `nano-banana-pro` — 3 credits, text rendering and real-time info
- `flux-schnell` — 1 credit, quick mockups and ideation
- `imagen-3` — 1 credit, realistic photos and complex compositions
- `recraft-v4` — 1 credit, typography and design
- `recraft-v4-pro` — 3 credits, high-res design and art direction

## Aspect Ratios

1:1, 16:9, 9:16, 3:2, 2:3, 4:5, 5:4, 3:4, 4:3, 21:9, 9:21

## Styles

realistic, anime, artistic, none

## MCP Server

The MCP server (`pixelmuse-mcp`) provides three tools for AI agents:
- `generate_image` — Generate an image from a prompt
- `list_models` — List available models with credit costs
- `check_balance` — Check credit balance and plan info

Configure in Claude Code (`~/.claude/.mcp.json`):
```json
{
  "mcpServers": {
    "pixelmuse": {
      "command": "npx",
      "args": ["-y", "pixelmuse-mcp"],
      "env": { "PIXELMUSE_API_KEY": "your_key" }
    }
  }
}
```

## API

Base URL: `https://www.pixelmuse.studio/api/v1`
Auth: Bearer token (`pm_live_` prefix)
Endpoints:
- `POST /images` — Generate an image
- `GET /images/:id` — Get generation status
- `GET /account` — Account balance and plan info

## Prompt Templates

Templates are YAML files with variable substitution stored at `~/.config/pixelmuse-cli/prompts/`. Example:
```yaml
name: Blog Thumbnail
prompt: "A cinematic {{subject}} on a dark gradient background"
defaults:
  model: nano-banana-2
  aspect_ratio: "16:9"
variables:
  subject: "code editor with syntax highlighting"
```

## Credits

Credit-based pricing. 1-3 credits per generation depending on model. Free credits included on signup. Top up at pixelmuse.studio.

## License

Business Source License 1.1 (BSL 1.1). Free for any use except competing image generation platforms. Converts to MIT on 2030-03-01.