PixVerse CLI — Master Skill

What is PixVerse CLI

PixVerse CLI is the official command-line interface for PixVerse — an AI-powered creative platform for generating videos and images. It is essentially a UI-free version of the PixVerse website: all features, models, and parameters are aligned with the web experience at app.pixverse.ai.

It is designed for:

• AI agents (primary) — structured JSON output, deterministic exit codes, and pipeable commands for autonomous workflows (Claude Code, Cursor, Codex, custom agents)
• Developers & power users — scriptable video/image generation without leaving the terminal
• Automation — batch processing, CI/CD pipelines, content production workflows

Key facts:

• Generating content consumes credits from the user's PixVerse account (same pricing as the website)
• Only subscribed users can use the CLI — see subscription plans
• All output can be returned as structured JSON via --json flag
• English only

Installation

npm install -g pixverse

Or run without installing:

npx pixverse

Verify:

pixverse --version

Requires Node.js >= 20.

Quick Start

# 1. Install
npm install -g pixverse

# 2. Authenticate (OAuth device flow — opens browser)
pixverse auth login --json

# 3. Create a video (waits for completion by default)
RESULT=$(pixverse create video --prompt "A cat astronaut floating in space" --json)
VIDEO_ID=$(echo "$RESULT" | jq -r '.video_id')

# 4. Download the result
pixverse asset download $VIDEO_ID --json

To skip waiting and poll later:

RESULT=$(pixverse create video --prompt "A cat astronaut floating in space" --no-wait --json)
VIDEO_ID=$(echo "$RESULT" | jq -r '.video_id')
pixverse task wait $VIDEO_ID --json
pixverse asset download $VIDEO_ID --json

Windows users: For a full PowerShell pipeline example (T2I → I2V → sound → upscale → download), see skills/examples/windows/powershell-text-to-video.ps1.

Authentication

PixVerse CLI uses OAuth device flow — no need to manually copy tokens:

1. Run pixverse auth login --json
2. The CLI prints an authorization URL
3. Open the URL in your browser and authorize
4. The token is stored automatically in ~/.pixverse/

Details:

• Token is valid for 30 days
• CLI sessions are independent from your web/app sessions
• If token expires (exit code 3), re-run pixverse auth login --json
• Set PIXVERSE_TOKEN environment variable to override the stored token
• Run pixverse auth status --json to check login state and credits

Capabilities Overview

Looking up models or parameters? Don't wait until you're generating — read the relevant capabilities file directly:

• Video models & constraints → skills/capabilities/create-video.md (Model Reference section)
• Image models & constraints → skills/capabilities/create-and-edit-image.md (Model Reference section)

Model Quick Reference

Use this to pick a model before diving into a sub-skill.

Video Models (pixverse create video --model <value>)

Image Models (pixverse create image --model <value>)

For full parameter constraints (aspect ratios, quality per model, mode support), read the capabilities files listed above.

Workflow Skills

Reference Materials

Located in skills/references/. These are read-only knowledge bases that capabilities and workflows draw from — no CLI commands, just curated design knowledge.

All Commands

Global Flags

Every command supports --json. All examples in skills use --json for machine-readable output.

Interactive mode: Run any creation command without arguments (and without --json) to enter the interactive wizard.

Output Contract

JSON mode (--json)

• stdout: Pure JSON only. No spinners, no progress text, no decorative output.
• stderr: All errors, warnings, and diagnostic messages.
• Parse stdout with jq or any JSON parser.

Exit Codes

Workspace error auto-recovery

When a request fails because the active workspace is no longer accessible (e.g. user was removed from a team), the CLI automatically resets to personal workspace (ID=0) and asks you to retry. This does not trigger when --workspace-id override is active or the failing request is a workspace management command.

Error handling pattern

RESULT=$(pixverse create video --prompt "A sunset over mountains" --json 2>/tmp/pv_err)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  VIDEO_ID=$(echo "$RESULT" | jq -r '.video_id')
  echo "Success: $VIDEO_ID"
  pixverse asset download $VIDEO_ID --json
elif [ $EXIT_CODE -eq 3 ]; then
  echo "Token expired, re-authenticating..."
  pixverse auth login --json
elif [ $EXIT_CODE -eq 4 ]; then
  echo "Not enough credits"
  pixverse account info --json | jq '.credits'
elif [ $EXIT_CODE -eq 5 ]; then
  echo "Generation failed — check prompt or parameters"
  cat /tmp/pv_err
else
  echo "Error (code $EXIT_CODE)"
  cat /tmp/pv_err
fi