Skip to main content
Assets are the images and videos in your Pixa workspace. Collections let you organize them into groups. Both are fully manageable from the CLI and MCP.

​
Assets

​
CLI commands

SubcommandDescription
assets listList assets (--limit, --after, --collection, --tag, --status)
assets upload <file_or_url>Upload a local file or import from a URL
assets get <asset_id>Get asset metadata
assets search <query>Search 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

​
MCP tools

The assets tool supports list, search, and get actions. Use the upload tool to import from URLs or get a one-time upload URL for local files.

​
Upload a file

pixa assets upload product.png --json

{
  "ok": true,
  "data": {
    "id": "ast_abc123",
    "url": "https://assets.pixa.dev/ast_abc123.png",
    "content_type": "image/png"
  }
}

​
Upload to a collection

pixa assets upload product.png --collection col_xyz789 --json

​
Import from a URL

pixa assets upload "https://example.com/photo.jpg" --json

​
Batch upload

Upload multiple files using a shell loop: 
for file in ./photos/*.png; do
  pixa assets upload "$file" --collection col_xyz789 --json
done

​
List assets with filters

# All assets
pixa assets list --json

# Filter by collection
pixa assets list --collection col_xyz789 --json

# Filter by tag
pixa assets list --tag "product" --json

# Filter by status
pixa assets list --status ready --json

​
Search assets

Search uses semantic similarity — describe what you are looking for in natural language: 
pixa assets search "red sneakers on white background" --limit 10 --json
Semantic search requires a Business tier subscription.

​
Download assets

pixa assets download ast_abc123 --json

​
Tag and untag assets

# Add tags
pixa assets tag ast_abc123 product hero --json

# Remove tags
pixa assets untag ast_abc123 hero --json

​
Delete assets

pixa assets delete ast_abc123 --json

# Delete multiple
pixa assets delete ast_abc123 ast_def456 ast_ghi789 --json

​
Collections

Collections are named groups of assets. Use them to organize uploads, target batch operations, and keep related assets together.

​
CLI commands

SubcommandDescription
collections listList 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

​
MCP actions

The collections tool supports list, search, get, and create actions.

​
List collections

pixa collections list --json

​
Create a collection

pixa collections create "Summer Campaign" --json

​
Search collections

pixa collections search "campaign" --json

​
Delete a collection

pixa collections delete col_xyz789 --json

​
Common workflows

​
Upload and organize

# Create a collection
pixa collections create "Product Photos Q3" --json

# Upload files into it
for file in ./product-photos/*.png; do
  pixa assets upload "$file" --collection col_xyz789 --json
done

​
Search and process

# Find relevant assets
pixa assets search "outdoor furniture" --limit 5 --json

# Process a specific result
pixa run remove-bg ast_abc123 --json

​
Move assets between collections

pixa assets move ast_abc123 ast_def456 col_newcol --json