# Command Reference

> Every picx-cli command, its flags, and example invocations.

Every command supports a `--json` flag for structured output — use it for scripts and AI agents instead of the default human-readable table.

## Generation

### `picx image <prompt>`

Generate an image from a text prompt.

| Flag | Values | Description |
| --- | --- | --- |
| `--model` | model ID | Omit for the account default. |
| `--size` | `1K` \| `2K` \| `4K` | Output resolution. |
| `--aspect-ratio` | `1:1` \| `16:9` \| `9:16` \| `4:3` \| `3:2` | Omit for square. |
| `--n` | `1`-`10` | Number of images to generate. |

```bash
picx image "a sunset over mountains, oil painting style"

picx image "neon cyberpunk city at night" \
  --model gemini-3.1-flash-image-preview \
  --size 2K --aspect-ratio 16:9
```

Response:

```json
{
  "images": [
    {
      "url": "https://cdn.picxstudio.com/api/generated/image_8871aa96.png",
      "id": "img_537f439a4e58",
      "model": "gemini-3.1-flash-image-preview",
      "size": "2K",
      "aspect_ratio": "16:9"
    }
  ],
  "credits_used": 53,
  "total_images": 1
}
```

### `picx image edit <instruction> -i <path|url>`

Edit one or more existing images with an AI instruction.

| Flag | Values | Description |
| --- | --- | --- |
| `-i`, `--image` | path or HTTPS URL | Input image, repeatable 1-5 times. A local path is uploaded for you; an HTTPS URL is used as-is. |
| `-m`, `--model` | model ID | Omit for the account default. |
| `-s`, `--size` | `1K` \| `2K` \| `4K` | Omit to preserve the original. |

```bash
# A local file is uploaded for you
picx image edit "remove background, add clean white studio backdrop" \
  -i ./photo.jpg -s 2K

# Or pass an HTTPS URL directly, repeat -i for multiple images
picx image edit "make it nighttime" \
  -i https://cdn.picxstudio.com/api/generated/img.png
```

### `picx video [prompt]`

Generate a video in one of seven modes. Asynchronous — returns a job id immediately, then poll with `picx job <id>`. The `prompt` argument is required for every mode **except** `lipsync`, which is driven entirely by its audio track.

| Flag | Values | Description |
| --- | --- | --- |
| `--mode` | `text` \| `image` \| `reference` \| `frames` \| `extend` \| `lipsync` \| `edit` | Generation mode. Default `text`. |
| `--duration` | seconds | Video duration. |
| `--resolution` | `480p` \| `720p` \| `1080p` | Output resolution. |
| `--sound` / `--no-sound` | — | Enable (default) or disable audio generation. |
| `--image` | URL | Seed image (modes `image`, `edit`). |
| `--reference` | URL(s) | Style reference image URL(s), repeatable (mode `reference`). |
| `--start-frame` | URL | Start frame (mode `frames`). |
| `--end-frame` | URL | End frame (mode `frames`, optional). |
| `--source-video` | URL | Source video (modes `extend`, `lipsync`, `edit`). |
| `--audio` | URL | Audio track (mode `lipsync`). |

Each mode requires a specific set of fields:

| Mode | Prompt | Also requires |
| --- | --- | --- |
| `text` | required | — |
| `image` | required | `--image` |
| `reference` | required | `--reference` (1 or more) |
| `frames` | required | `--start-frame` (`--end-frame` optional) |
| `extend` | required | `--source-video` |
| `lipsync` | **none** | `--source-video` **and** `--audio` |
| `edit` | required | `--source-video` **and** `--image` |

```bash
# text mode (default)
picx video "a drone shot flying over a coastline" --duration 8 --resolution 1080p
# -> { "id": "gen_abc123", "status": "pending" }

# lipsync — no prompt, drive a face to speak an audio track
picx video --mode lipsync \
  --source-video https://cdn.picxstudio.com/api/generated/clip.mp4 \
  --audio https://cdn.picxstudio.com/api/generated/voice.mp3

# frames — interpolate between a start and (optional) end frame
picx video "smooth morph between the two shots" --mode frames \
  --start-frame https://cdn.picxstudio.com/api/generated/a.png \
  --end-frame https://cdn.picxstudio.com/api/generated/b.png
```

### `picx job <id>`

Poll a generation job's status and get the result URL when done.

```bash
picx job gen_abc123
# poll every 10-15s until status is "completed" or "failed"
```

## Assets

### `picx upload <file>`

Upload a local file to get an HTTPS URL for edit/video input.

```bash
picx upload ./photo.jpg
```

### `picx assets list`

List uploaded and generated assets in your account.

### `picx assets rm <id>`

Delete an asset by id.

```bash
picx assets rm asset_abc123
```

## Discovery

### `picx models`

List available models and their live credit costs. Always re-check this before a cost-sensitive script — costs change as PicX adds models.

### `picx templates search [query]`

Search the PicX template catalogue (~50K curated prompts). The `query` argument is optional; filter with the flags below.

| Flag | Values | Description |
| --- | --- | --- |
| `--media-type` | `image` \| `video` | Filter by media type. |
| `--topic` | topic string | Filter by topic bucket (see caveat below). |
| `--model` | model ID | Only templates built for that target model. |
| `--featured` | — | Only editor-picked templates. |
| `--trending` | — | Only currently trending templates. |
| `--tags` | tag(s) | Filter by tags, matched as a set. |
| `--limit` | `1`-`100` | Page size, default 30. |
| `--offset` | `≥0` | Rows to skip, default 0. |

```bash
picx templates search "product photography"
picx templates search --media-type video --model gemini-3.1-flash-image-preview --limit 5
picx templates search --tags cinematic portrait --featured
```

Three behaviours to know when reading results back:

> [!NOTE]
> - **`total` is an estimate, not a count.** The catalogue is too large to count on every query, so the server returns `offset + page length + 1` when more rows exist. To exhaust results, keep increasing `--offset` by `--limit` until a page comes back with fewer rows than `--limit` — that's the last page.
> - **The `topic` filter works, but the `topic` field is always `null`.** Topic is a query-time keyword bucket, not a stored per-row column. Filter by it; don't expect to read it back off a result.
> - **A `null` prompt means a premium/gated template, not missing data.** Such a row still carries its title, preview, and tags, but its prompt is redacted for public API keys and can't be fed into a generation.

### `picx templates get <id>`

Get a single template by id. A `null` `prompt` in the response means the template is premium/gated (redacted for public keys), not that data is missing.

```bash
picx templates get 38599 --json
```

## Account

### `picx history`

List your recent generations.

| Flag | Values | Description |
| --- | --- | --- |
| `--type` | `image` \| `video` | Filter by generation type. |
| `--status` | `pending` \| `completed` \| `failed` | Filter by status. |
| `--limit` | `1`-`50` | Max results, default 20. |

```bash
picx history --type video --status completed --limit 10
```

### `picx whoami`

Check API key authentication status and account identity. There is no separate `picx auth` command — this is the equivalent.

### `picx balance`

Show current credit balance.

### `picx usage`

Show credit usage for a period.

| Flag | Values | Description |
| --- | --- | --- |
| `--period` | `7d` \| `30d` \| `90d` | Time window, default `30d`. |

```bash
picx usage --period 90d
```

### `picx tier`

Show your account's current plan/tier.

## Webhooks

These inspect and replay webhook deliveries — the API-key-authorized subset of the webhook surface. Creating, editing, and deleting webhook endpoints is a session-authenticated dashboard operation and is not available to an API key.

### `picx webhook deliveries <webhook_id>`

List the delivery attempts for one registered webhook endpoint. Use it to find the `delivery_id` you need for a redelivery.

```bash
picx webhook deliveries wh_abc123
```

### `picx webhook redeliver <delivery_id>`

Replay a stored webhook delivery. This re-fires the same signed payload to the endpoint — a **real outbound POST** to the customer's URL. It does not regenerate anything and does not cost credits.

```bash
picx webhook redeliver del_abc123
```

### `picx generation deliveries <generation_id>`

List the webhook delivery attempts for a single generation — answers "did the webhook for *this* render fire, and with what response?"

```bash
picx generation deliveries gen_abc123
```

## MCP

### `picx mcp install --client <claude|cursor>`

Install and configure the PicX MCP server for a client. See [Connect Claude Desktop](/docs/mcp/connect-claude-desktop) or [Connect Cursor](/docs/mcp/connect-cursor) for what this does manually.

```bash
picx mcp install --client claude
```

### `picx mcp serve`

Start the PicX MCP stdio server locally — the server a client launches to talk MCP over stdio.

```bash
picx mcp serve
```

### `picx mcp doctor`

Health-check the MCP connection and credentials — verifies the endpoint is reachable and the configured API key authenticates before you rely on it.

```bash
picx mcp doctor
```

## FAQ

### Which commands are free vs. which cost credits?

`picx image`, `picx image edit`, and `picx video` deduct credits per the live costs shown by `picx models`. Every other command — `whoami`, `balance`, `usage`, `tier`, `history`, `assets list`, `assets rm`, `upload`, `templates search`, `templates get`, `webhook deliveries`, `webhook redeliver`, `generation deliveries`, `mcp install`, `mcp doctor` — is free. Note that `webhook redeliver` triggers a real outbound POST to the endpoint even though it costs no credits.

### Is there a way to see every command's help text from the terminal?

Yes — `picx --help` lists top-level commands, and `picx <command> --help` shows that command's flags. This page mirrors that but with runnable examples.

### Why is there no `picx auth` command?

Auth status is reported by `picx whoami` instead — it confirms the key works and returns account identity in one step, rather than a separate bare "is this key valid" check.