pixcli

The creative toolkit for AI agents — generate images, videos, voiceover, music, and sound effects from the command line. Create and edite anything.

Install

npm install -g pixcli

Or run without installing (use --yes to skip the install prompt — required for AI agents):

npx --yes pixcli image "a red fox in a forest"

Auth

export PIXCLI_API_KEY="px_live_..."

Get your key at pixcli.shellbot.sh.

Commands

pixcli image <prompt> — Generate images

pixcli image "Studio product shot of wireless earbuds, soft lighting" -r 16:9 -q high -o earbuds.png
pixcli image "Abstract pattern, dark blue and cyan" -n 4
pixcli image "Red sneaker, centered, clean edges" -t -o sneaker.png
pixcli image "Same product, warm background" --from product.png -o warm.png

| Option | Default | Description | |--------|---------|-------------| | -r, --ratio | 1:1 | 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 | | -q, --quality | standard | draft, standard, high | | -t, --transparent | false | Transparent background (PNG) | | -n, --count | 1 | Number of images (1-4) | | --from | — | Source image for I2I | | -m, --model | auto | Model ID (bypasses auto-classification) | | -o, --output | auto | Output path | | --json | false | JSON output |

pixcli edit <prompt> — Edit images

pixcli edit "Remove the background" -i photo.jpg -o photo-nobg.png
pixcli edit "Upscale to max resolution" -i hero.png -q high -o hero-4k.png
pixcli edit "Apply the style from the reference" -i photo.jpg -i style-ref.jpg

| Option | Default | Description | |--------|---------|-------------| | -i, --image | required | Source image (repeatable) | | -q, --quality | standard | draft, standard, high | | -m, --model | auto | Model ID | | -o, --output | auto | Output path | | --json | false | JSON output |

pixcli video <prompt> — Generate video

pixcli video "Slow orbit around the product" --from product.png -d 5 -o reveal.mp4
pixcli video "A cat walking through a garden" -o cat.mp4
pixcli video "The cat jumps over a fence" --from cat.mp4 --extend -o extended.mp4

| Option | Default | Description | |--------|---------|-------------| | --from | — | Source image (I2V) or video (extend) | | -d, --duration | 5 | Duration in seconds (2-10) | | -r, --ratio | 16:9 | 16:9, 9:16, 1:1, 4:3, 3:4 | | -q, --quality | standard | draft, standard, high | | -m, --model | auto | Model ID | | -o, --output | auto | Output path | | --extend | false | Extend source video | | --json | false | JSON output |

pixcli voice <text> — Text-to-speech

pixcli voice "Welcome to the future of productivity." -o voiceover.mp3
pixcli voice "Bienvenidos." --voice Sarah --language spa -o vo-es.mp3

| Option | Default | Description | |--------|---------|-------------| | --voice | Rachel | Voice preset (Rachel, Aria, Roger, Sarah, Laura, Charlie, George, etc.) | | --language | auto | ISO 639-1 code (eng, spa, fra, deu, jpn, ...) | | -o, --output | auto | Output path (.mp3) | | --json | false | JSON output |

pixcli music <prompt> — Generate music

pixcli music "Ambient electronic, minimal beats, corporate feel" -d 45 -o bg.mp3

| Option | Default | Description | |--------|---------|-------------| | -d, --duration | 30 | Duration in seconds (3-120) | | -o, --output | auto | Output path (.mp3) | | --json | false | JSON output |

pixcli sfx <prompt> — Generate sound effects

pixcli sfx "Smooth cinematic whoosh" -d 1.5 -o whoosh.mp3
pixcli sfx "Soft digital click" -d 0.5 -o click.mp3

| Option | Default | Description | |--------|---------|-------------| | -d, --duration | 5 | Duration in seconds (0.5-22) | | -o, --output | auto | Output path (.mp3) | | --json | false | JSON output |

Global options

| Option | Description | |--------|-------------| | --key <key> | Override PIXCLI_API_KEY | | --api-url <url> | Override API URL (default: https://pixcli.shellbot.sh) | | --version | Show version | | --help | Show help |

JSON mode

All commands support --json for machine-readable output:

pixcli image "hero shot" --json | jq '.files[0].path'

{
  "job_id": "abc123",
  "status": "completed",
  "files": [{ "path": "hero-shot.png", "width": 1024, "height": 1024, "mime_type": "image/png" }],
  "model": "flux-pro",
  "cost": 100000,
  "elapsed_ms": 12340
}

Models

Image generation

flux-pro, flux-dev, seedream-v5, nano-banana-pro, nano-banana-2, imagen-4, imagen-4-fast, gpt-image-1

Image editing

seedream-v5-edit, phota-enhance, rembg, recraft-upscale, aura-sr

Video

kling-v3-pro-i2v, veo3-i2v, wan-v2-i2v, minimax-i2v, ltx-t2v, veo3-t2v, grok-extend-video

Audio

elevenlabs-tts-v3, elevenlabs-music, elevenlabs-sfx

Architecture

Project structure

cli/
├── src/
│   ├── index.ts              ← Entrypoint: autoupgrade check → Commander setup → parse
│   ├── commands/
│   │   ├── image.ts          ← Generate images (T2I, I2I)
│   │   ├── edit.ts           ← Edit images (upscale, rembg, style transfer)
│   │   ├── video.ts          ← Generate / extend video (T2V, I2V)
│   │   ├── voice.ts          ← Text-to-speech
│   │   ├── music.ts          ← Music generation
│   │   ├── sfx.ts            ← Sound effects generation
│   │   └── job.ts            ← Check job status / results
│   └── lib/
│       ├── config.ts         ← Version, API key & base URL resolution
│       ├── client.ts         ← HTTP client (PixClient: post, get, upload, stream)
│       ├── poller.ts         ← Async job polling until terminal state
│       ├── upload.ts         ← Local file → presigned upload → URL
│       ├── download.ts       ← Asset URLs → local files
│       ├── output.ts         ← Spinners, JSON mode, human-readable output
│       └── autoupgrade.ts    ← Self-upgrade check (hourly, from npm registry)
└── package.json

Request flow

┌─────────────────────────────────────────────────────┐
│  AI Agent / User                                    │
│  $ pixcli image "a red fox" -r 16:9 -o fox.png     │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
              ┌────────────────┐
              │  Autoupgrade   │  Check npm registry (cached, 1x/hour)
              │  (silent)      │  If newer → npm install -g → re-exec
              └───────┬────────┘
                      │
                      ▼
              ┌────────────────┐
              │  Commander     │  Parse args, resolve API key & base URL
              │  (index.ts)    │
              └───────┬────────┘
                      │
                      ▼
              ┌────────────────┐  POST /api/v1/generate
              │  Submit Job    │──────────────────────────┐
              │  (PixClient)   │                          │
              └───────┬────────┘                          │
                      │                                   ▼
                      │                      ┌────────────────────┐
                      │                      │  pixcli API        │
                      │                      │  (Cloudflare       │
                      │                      │   Workers)         │
                      │                      │                    │
                      │                      │  • Classify prompt │
                      │                      │  • Route to model  │
                      │                      │  • Queue job       │
                      │                      └────────────────────┘
                      │
                      ▼
              ┌────────────────┐  GET /api/v1/jobs/:id
              │  Poll Job      │  (every 2s, up to 10 min)
              │  (poller.ts)   │
              └───────┬────────┘
                      │
                      │  status: completed
                      ▼
              ┌────────────────┐  GET /api/v1/jobs/:id/result
              │  Get Result    │  → asset URLs
              └───────┬────────┘
                      │
                      ▼
              ┌────────────────┐
              │  Download      │  Stream assets → local files
              │  (download.ts) │
              └───────┬────────┘
                      │
                      ▼
              ┌────────────────┐
              │  Output        │  Human: spinner + file paths
              │  (output.ts)   │  --json: structured JSON to stdout
              └────────────────┘

Command lifecycle (all commands follow the same pattern)

1. Autoupgrade   →  Check for new version (cached hourly)
2. Parse args    →  Commander validates flags, resolves API key
3. Upload        →  If --from / -i provided, upload local files to get URLs
4. Submit        →  POST to API, receive job_id
5. Poll          →  GET job status every 2s until completed/failed
6. Download      →  Fetch result assets, write to disk
7. Output        →  Print paths (human) or JSON (--json)

Auto-upgrade

The CLI checks the npm registry for a newer published version on each invocation, but at most once per hour (cached in /tmp/pixcli-upgrade-check.json). If a new version is found, it runs npm install -g pixcli@latest silently and re-executes the original command. Set PIXCLI_NO_AUTOUPGRADE=1 to disable.

Requirements

• Node.js 18+
• PIXCLI_API_KEY environment variable

License

MIT ixigo.com