{"id":47813211,"url":"https://github.com/starmorph/pixelmuse-cli","last_synced_at":"2026-04-03T18:19:08.977Z","repository":{"id":341374205,"uuid":"1169527844","full_name":"starmorph/pixelmuse-cli","owner":"starmorph","description":"AI image generation from the terminal — CLI, TUI, and MCP server for text-to-image with Flux, Imagen, Recraft, and more","archived":false,"fork":false,"pushed_at":"2026-03-16T19:54:40.000Z","size":63557,"stargazers_count":2,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-17T06:43:18.834Z","etag":null,"topics":["ai","ai-art","api-client","claude","cli","creative-tools","developer-tools","flux","generative-ai","image-generation","imagen","mcp","mcp-server","model-context-protocol","nodejs","recraft","terminal","text-to-image","tui","typescript"],"latest_commit_sha":null,"homepage":"https://www.pixelmuse.studio/developers/cli","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/starmorph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T20:27:18.000Z","updated_at":"2026-03-15T13:46:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/starmorph/pixelmuse-cli","commit_stats":null,"previous_names":["starmorph/pixelmuse-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/starmorph/pixelmuse-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starmorph%2Fpixelmuse-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starmorph%2Fpixelmuse-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starmorph%2Fpixelmuse-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starmorph%2Fpixelmuse-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/starmorph","download_url":"https://codeload.github.com/starmorph/pixelmuse-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starmorph%2Fpixelmuse-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31368163,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-art","api-client","claude","cli","creative-tools","developer-tools","flux","generative-ai","image-generation","imagen","mcp","mcp-server","model-context-protocol","nodejs","recraft","terminal","text-to-image","tui","typescript"],"created_at":"2026-04-03T18:19:08.342Z","updated_at":"2026-04-03T18:19:08.960Z","avatar_url":"https://github.com/starmorph.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/banner.png\" alt=\"pixelmuse\" width=\"700\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAI image generation from the terminal.\u003c/strong\u003e\u003cbr/\u003e\n  CLI, interactive TUI, and MCP server — powered by the \u003ca href=\"https://pixelmuse.studio\"\u003ePixelmuse\u003c/a\u003e API.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/pixelmuse\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/pixelmuse.svg\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/pixelmuse\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/pixelmuse.svg\" alt=\"npm downloads\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/starmorph/pixelmuse-cli/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/starmorph/pixelmuse-cli/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/starmorph/pixelmuse-cli/actions/workflows/security.yml\"\u003e\u003cimg src=\"https://github.com/starmorph/pixelmuse-cli/actions/workflows/security.yml/badge.svg\" alt=\"Security\" /\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-BSL%201.1-blue.svg\" alt=\"License: BSL 1.1\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg\" alt=\"Node.js\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./assets/demos/pixelmuse-cli-demo.gif\" alt=\"Pixelmuse CLI demo\" width=\"700\" /\u003e\u003c/p\u003e\n\n---\n\n## Why Pixelmuse?\n\n- **One command, any model.** Flux, Imagen 3, Recraft V4, and more — switch models with a flag, no separate accounts or API keys.\n- **Built for developer workflows.** Pipe from stdin, JSON output for scripting, watch mode for prompt iteration, MCP server for AI agents.\n- **Predictable credit pricing.** 1–7 credits per generation, most models just 1 credit. Free credits on signup.\n\n## Get Started\n\n```bash\nnpm install -g pixelmuse\npixelmuse setup\n```\n\nThe setup wizard creates your account (opens browser), configures your API key, and optionally sets up the MCP server for Claude Code, Cursor, or Windsurf. New accounts include **15 free credits**.\n\n\u003e Requires Node.js 20+. For terminal image previews, install [chafa](https://hpjansson.org/chafa/) (`brew install chafa` / `sudo apt install chafa`).\n\n## Quick Start\n\n```bash\n# Generate an image\npixelmuse \"a cat floating through space\"\n\n# Choose model and aspect ratio\npixelmuse \"neon cityscape at night\" -m recraft-v4 -a 16:9\n\n# Apply a style\npixelmuse \"mountain landscape\" -s anime -a 21:9\n\n# Save to specific path\npixelmuse \"app icon, minimal\" -o icon.png\n```\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./assets/demos/account-models.gif\" alt=\"Account and model overview\" width=\"700\" /\u003e\u003c/p\u003e\n\n## Prompt Templates\n\nSave reusable prompts as YAML files with variables and default settings.\n\n```bash\n# Scaffold a new template\npixelmuse template init product-shot\n\n# Generate with a template\npixelmuse template use blog-thumbnail --var subject=\"React hooks guide\"\n\n# List all templates\npixelmuse template list\n```\n\n\nTemplates are stored at `~/.config/pixelmuse-cli/prompts/`:\n\n```yaml\n# blog-thumbnail.yaml\nname: Blog Thumbnail\ndescription: Dark-themed blog post thumbnail\nprompt: \u003e\n  A cinematic {{subject}} on a dark gradient background,\n  dramatic lighting, 8K resolution\ndefaults:\n  model: nano-banana-2\n  aspect_ratio: \"16:9\"\nvariables:\n  subject: \"code editor with syntax highlighting\"\ntags: [blog, thumbnail, dark]\n```\n\n## Interactive TUI\n\nA full terminal UI for visual browsing, generation wizards, gallery, and account management:\n\n```bash\npixelmuse ui\n```\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./assets/demos/tui-generate.gif\" alt=\"Interactive TUI generation\" width=\"700\" /\u003e\u003c/p\u003e\n\n## Scripting \u0026 Pipes\n\n```bash\n# Pipe prompt from stdin\necho \"hero banner for SaaS landing page\" | pixelmuse -o hero.png\ncat prompt.txt | pixelmuse -m recraft-v4\n\n# JSON output for scripting\npixelmuse --json \"logo concept\" | jq .output_path\n\n# Watch mode — regenerates when prompt file changes\npixelmuse --watch prompt.txt -o output.png\n\n# Skip preview, copy to clipboard\npixelmuse \"avatar\" --no-preview --clipboard\n```\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./assets/demos/help.gif\" alt=\"CLI help and commands\" width=\"700\" /\u003e\u003c/p\u003e\n\n## MCP Server (Claude Code, Cursor, Windsurf)\n\nThe MCP server lets AI agents generate images, list models, and check your balance — no manual CLI steps needed.\n\n**Claude Code** — add to `~/.claude/.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pixelmuse\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"pixelmuse-mcp\"],\n      \"env\": {\n        \"PIXELMUSE_API_KEY\": \"pm_live_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n**Cursor / Windsurf** — add to your MCP settings:\n\n```json\n{\n  \"pixelmuse\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"pixelmuse-mcp\"],\n    \"env\": {\n      \"PIXELMUSE_API_KEY\": \"pm_live_your_key_here\"\n    }\n  }\n}\n```\n\nThe agent gets three tools:\n\n| Tool | What it does |\n|------|-------------|\n| `generate_image` | Generate an image from a prompt with model, aspect ratio, style, and output path. |\n| `list_models` | List all available models with credit costs. |\n| `check_balance` | Check your credit balance and plan info. |\n\n**Example prompts for your AI agent:**\n\n- \"Generate a hero image for my landing page, 16:9, save to `./public/hero.png`\"\n- \"Create a blog thumbnail about React hooks using the anime style\"\n- \"What Pixelmuse models are available?\"\n\n## Which Interface?\n\nPixelmuse ships four interfaces. Pick the one that fits your workflow — they all use the same API and credentials.\n\n| | **CLI** | **TUI** | **MCP Server** | **Claude Skill** |\n|---|---|---|---|---|\n| **What it is** | Command-line tool | Interactive terminal UI | AI agent tool server | Claude Code prompt template |\n| **Launch** | `pixelmuse \"prompt\"` | `pixelmuse ui` | Auto-starts with Claude/Cursor | Auto-triggers on keywords |\n| **Best for** | Scripting, automation, CI/CD | Visual browsing, exploring models | Letting AI agents generate images | Generating images mid-conversation |\n| **Input** | Flags, stdin, pipe, watch mode | Guided wizard with menus | AI decides params from natural language | Natural language to Claude |\n\n**Rule of thumb:**\n- **You type the prompt** → CLI or TUI\n- **AI types the prompt** → MCP Server or Claude Skill\n- **Quick one-off** → CLI\n- **Browsing/exploring** → TUI\n\n## Models\n\n| Model | Credits | Best For |\n|-------|---------|----------|\n| **Nano Banana 2** (default) | 1 | Speed, text rendering, world knowledge |\n| Nano Banana Pro | 4 | Text rendering, real-time info, multi-image editing |\n| Flux Schnell | 1 | Quick mockups, ideation |\n| Google Imagen 3 | 1 | Realistic photos, complex compositions |\n| Recraft V4 | 1 | Typography, design, composition |\n| Recraft V4 Pro | 7 | High-res design, art direction |\n\n## CLI Reference\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `pixelmuse setup` | First-time setup wizard (account, MCP, defaults) |\n| `pixelmuse \"prompt\"` | Generate an image (default command) |\n| `pixelmuse models` | List available models with costs |\n| `pixelmuse account` | Account balance and usage stats |\n| `pixelmuse history` | Recent generations table |\n| `pixelmuse open \u003cid\u003e` | Open a generation in system viewer |\n| `pixelmuse login` | Authenticate with API key |\n| `pixelmuse logout` | Remove stored credentials |\n| `pixelmuse template \u003ccmd\u003e` | Manage prompt templates |\n| `pixelmuse ui` | Launch interactive TUI |\n\n### Flags\n\n| Flag | Description |\n|------|-------------|\n| `-m, --model` | Model ID (default: `nano-banana-2`) |\n| `-a, --aspect-ratio` | Aspect ratio (default: `1:1`) |\n| `-s, --style` | `realistic`, `anime`, `artistic`, `none` |\n| `-o, --output` | Output file path |\n| `--json` | Machine-readable JSON output |\n| `--no-preview` | Skip terminal image preview |\n| `--open` | Open result in system viewer |\n| `--clipboard` | Copy image to clipboard |\n| `--watch \u003cfile\u003e` | Watch prompt file, regenerate on save |\n| `--no-save` | Don't save image to disk |\n\n## Configuration\n\nSettings at `~/.config/pixelmuse-cli/config.yaml`:\n\n```yaml\ndefaultModel: nano-banana-2\ndefaultAspectRatio: \"1:1\"\ndefaultStyle: none\nautoPreview: true\nautoSave: true\n```\n\n| Path | Contents |\n|------|----------|\n| `~/.config/pixelmuse-cli/config.yaml` | User settings |\n| `~/.config/pixelmuse-cli/auth.json` | API key (fallback if keychain unavailable) |\n| `~/.config/pixelmuse-cli/prompts/` | Prompt template YAML files |\n| `~/.local/share/pixelmuse-cli/generations/` | Auto-saved generation images |\n\n## Links\n\n- [Pixelmuse](https://www.pixelmuse.studio) — Platform home\n- [Sign up](https://www.pixelmuse.studio/sign-up) — Create an account (free credits included)\n- [API keys](https://www.pixelmuse.studio/settings/api-keys) — Manage API keys\n- [API docs](https://www.pixelmuse.studio/developers) — Full API reference (Scalar)\n- [Get credits](https://www.pixelmuse.studio/get-credits) — Buy credit packs\n\u003c!-- - [YouTube demo](YOUR_YOUTUBE_URL) — Full walkthrough video --\u003e\n\n## License\n\nBusiness Source License 1.1 (BSL 1.1). See [LICENSE](./LICENSE) for details.\n\nFree for any use except offering a competing image generation API or platform. Converts to GPL-2.0 on 2029-03-01.\n\nCopyright 2025 StarMorph LLC.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarmorph%2Fpixelmuse-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarmorph%2Fpixelmuse-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarmorph%2Fpixelmuse-cli/lists"}