CLI Command Reference

Global flags

These flags are available on every command:

Flag	Description	Default
`--json`	Output in JSON format (recommended for AI agents)	`false`
`--timeout`	Request timeout	`10m`

Commands

auth

Manage authentication and credentials.

Subcommand	Description
`auth login`	Log in with a browser session (OAuth)
`auth logout`	Remove the stored session
`auth status`	Show current user, org, and environment

You can also authenticate by setting the PIXA_API_KEY environment variable.

run

Run tools, prompts, and pipelines. This is the primary entrypoint for agents. pixa run has subcommands for each mode of execution:

run prompt

Submit a natural-language prompt to Pixa’s AI agent. The agent analyzes your request and selects the appropriate tools.

pixa run prompt "remove the background from this photo" \
  --attachment photo.png --json

Flags:

Flag	Description
`--attachment`	Attach a file, URL, or asset ID (repeatable)
`--model`	Model ID for generation (e.g., `nano-banana-2`)
`--aspect-ratio`	Aspect ratio (e.g., `16:9`, `1:1`)
`--output-format`	Output format: `png`, `jpg`, or `webp`
`--num-variations`	Number of variations to generate
`--brand-library`	Brand library ID for brand-consistent generation
`--async`	Return immediately with job ID
`--dry-run`	Validate without executing
`--skip-save`	Don’t save results to the workspace
`--collection-id`	Save results to a specific collection
`--output`	Download result to this file path

JSON input (via flag or stdin):

pixa run prompt --json-input '{
  "message": "remove the background",
  "attachments": [{"url": "https://example.com/photo.png"}]
}' --json

echo '{
  "message": "remove the background",
  "attachments": [{"url": "photo.png"}],
  "generation_settings": {
    "model_id": "nano-banana-2",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "num_variations": 2,
    "brand_library_id": "<library-id>"
  }
}' | pixa run prompt --json

run pipeline

Run a saved pipeline by ID.

pixa run pipeline pl_abc123 \
  --input photo=./product.png \
  --input prompt="white background" \
  --json

Flags:

Flag	Description
`--input`	Node input as `name=value` (repeatable; value is file path, URL, asset ID, or text)
`--async`	Return immediately with job ID
`--dry-run`	Validate without executing
`--collection-id`	Save results to a specific collection

run remove-bg

Remove background from an image.

pixa run remove-bg product.png --json

run upscale

Upscale an image to higher resolution.

pixa run upscale product.png --scale 4 --json

Flag	Description	Default
`--scale`	Scale factor (`2` or `4`)	`2`

run expand

Extend an image with AI-generated content.

pixa run expand product.png --right 200 --bottom 100 --json

Flag	Description	Default
`--left`	Pixels to add on the left	`0`
`--right`	Pixels to add on the right	`0`
`--top`	Pixels to add on the top	`0`
`--bottom`	Pixels to add on the bottom	`0`

run model

Generate images or video with an AI model.

pixa run model "a product photo on white background" \
  --model nano-banana-2 --aspect-ratio 1:1 --json

Flag	Description	Default
`--model`	Model ID (run `pixa models` to browse)	—
`--aspect-ratio`	Aspect ratio (e.g., `16:9`, `1:1`)	—
`--output-format`	Output format: `png`, `jpg`, or `webp`	`png`
`--num-variations`	Number of variations to generate	`1`

All run subcommands also accept --async, --dry-run, --skip-save, --collection-id, --output, --set key=value, and --attachment name=value.

jobs

Inspect and manage long-running operations.

Subcommand	Description
`jobs get <id>`	Get job status and results
`jobs follow <id>`	Poll until completion (`--interval` to set polling frequency, default 2s)
`jobs cancel <id>`	Cancel a running job

models

Browse available AI models.

Subcommand	Description
`models list`	List all available models (`--limit` for pagination)
`models search <query>`	Search by name or capability
`models get <id>`	Get model details

assets

Manage media assets.

Subcommand	Description
`assets list`	List assets (`--limit`, `--after`, `--collection`, `--tag`, `--status`)
`assets upload <file_or_url>`	Upload a local file or import from a URL (`--collection` to target)
`assets get <asset_id>`	Get asset metadata
`assets search <query>`	Search assets by keyword or semantic similarity (`--limit`)
`assets download <asset_id>`	Download an asset to a local file
`assets delete <asset_id>...`	Delete one or more assets
`assets move <asset_id>... <collection_id>`	Move assets to a collection
`assets tag <asset_id> <tags>...`	Add tags to an asset
`assets untag <asset_id> <tags>...`	Remove tags from an asset

collections

Organize assets into groups.

Subcommand	Description
`collections list`	List all collections
`collections get <id>`	Get a collection by ID
`collections create [name]`	Create a new collection
`collections search <query>`	Search collections by name
`collections delete <id>`	Delete a collection

pipelines

Manage saved reusable workflows.

Subcommand	Description
`pipelines list`	List all pipelines (`--limit`, `--after`)
`pipelines get <id>`	Get pipeline details (nodes, edges)
`pipelines create`	Create a new pipeline (`--name` required)
`pipelines update <id>`	Update a pipeline
`pipelines search <query>`	Search pipelines by name
`pipelines delete <id>`	Delete a pipeline
`pipelines runs <id>`	List past runs of a pipeline
`pipelines node-types`	List available node types

brands

Manage brand libraries and identities.

Subcommand	Description
`brands list`	List all brand libraries with identity details
`brands get <id>`	Get a brand library’s details
`brands create`	Create a new brand library (`--name` required, `--website`, `--tagline`, `--description` optional)
`brands delete <id>`	Delete a brand library

personas

Manage AI personas for content generation.

Subcommand	Description
`personas list`	List all personas (`--brand` to filter by brand library)
`personas get <id>`	Get persona details
`personas create`	Create a new persona (`--brand`, `--name` required)

Create and manage shareable links to asset selections.

Subcommand	Description
`share-links list`	List all share links
`share-links get <id>`	Get a share link by ID
`share-links create`	Create a new share link (`--name` required, `--asset` or `--collection` to include)
`share-links contents <id>`	List assets in a share link
`share-links update <id>`	Modify a share link (`--add-asset`, `--remove-asset`)
`share-links delete <id>`	Delete a share link

Subcommand	Description
`tags list`	List all tags
`tags delete <name>`	Delete a tag

usage

View credits and usage history.

Subcommand	Description
`usage credits`	Show current credit balance and next refill date
`usage history`	View past credit transactions (`--limit`, `--after`)

update

Upgrade pixa to the latest version.

pixa update

Getting started

Tools & workflows

Reference

CLI Command Reference

Global flags

Commands

auth

run

run prompt

run pipeline

run remove-bg

run upscale

run expand

run model

jobs

models

assets

collections

pipelines

brands

personas

tags

usage

update

Getting started

Tools & workflows

Reference

​Global flags

​Commands

​auth

​run

​run prompt

​run pipeline

​run remove-bg

​run upscale

​run expand

​run model

​jobs

​models

​assets

​collections

​pipelines

​brands

​personas

​share-links

​tags

​usage

​update

Global flags

Commands

auth

run

run prompt

run pipeline

run remove-bg

run upscale

run expand

run model

jobs

models

assets

collections

pipelines

brands

personas

share-links

tags

usage

update