Native Pipeline CLI Skill

Run QCut's built-in TypeScript pipeline CLI (qcut-pipeline / bun run pipeline).

Additional resources

• For standalone CLI commands (generate, analyze, transcribe, models, help, output formats), see REFERENCE.md
• For YAML pipelines, API key management, project management, see reference-pipelines.md
• For ViMax commands (idea2video, script2video, novel2movie, portraits), see reference-vimax.md
• For editor core reference: connection, flags, batch limits, env vars, common workflows, see editor-core.md
• For editor media & project commands, project.json schema, see editor-media.md
• For editor timeline & editing commands, see editor-timeline.md
• For editor export, diagnostics, MCP, screen recording, UI, Moyin, screenshots, state control, see editor-output.md
• For editor AI commands: video analysis, transcription, AI generation, Remotion, navigator, see editor-ai.md
• For editor state automation: snapshots, event streams, correlation IDs, transactions, capabilities, and notification bridge endpoints, see editor-state-control.md

Step 1: Ensure QCut is Running

Before any editor:* command, check if QCut is running. If not, build and launch it.

# Check if QCut is running
curl -s --connect-timeout 2 http://127.0.0.1:8765/api/claude/health || echo "NOT_RUNNING"

If NOT_RUNNING:

bun run build                # Build first
bun run electron &           # Launch in background
sleep 5                      # Wait for startup

Step 2: Find Project, Media & Timeline

Most editor commands need --project-id, --media-id, or --element-id. Run these to discover them.

# 1. List projects → get project-id
bun run pipeline editor:navigator:projects

# 2. Open a project (navigates the editor)
bun run pipeline editor:navigator:open --project-id <project-id>

# 3. Switch to editor panel (navigator:open lands on the landing page, NOT the editor)
bun run pipeline editor:ui:switch-panel --panel video-edit

# 4. List media → get media-id values
bun run pipeline editor:media:list --project-id <project-id> --json

# 5. Export timeline → get track-id and element-id values
bun run pipeline editor:timeline:export --project-id <project-id> --json

Now you have the IDs needed for all other editor commands.

How to Run

bun run pipeline <command> [options]            # Dev (recommended)
bun run electron/native-pipeline/cli/cli.ts <command> [options]  # Direct source
qcut-pipeline <command> [options]               # Production binary

Quick Commands

bun run pipeline list-models                          # List all models
bun run pipeline generate-image -t "A cinematic portrait at golden hour"
bun run pipeline create-video -m kling_2_6_pro -t "Ocean waves at sunset" -d 5s
bun run pipeline generate-avatar -m omnihuman_v1_5 -t "Hello world" --image-url avatar.png
bun run pipeline analyze-video -i video.mp4 --analysis-type summary
bun run pipeline transcribe -i audio.mp3 --srt
bun run pipeline run-pipeline -c pipeline.yaml -i "A sunset" --no-confirm
bun run pipeline estimate-cost -m veo3 -d 8s

ViMax Quick Start

bun run pipeline vimax:idea2video --idea "A detective in 1920s Paris" -d 120
bun run pipeline vimax:script2video --script script.json --portraits registry.json
bun run pipeline vimax:novel2movie --novel book.txt --max-scenes 20

API Key Setup

Keys stored in ~/.qcut/.env (mode 0600).

bun run pipeline setup          # Create .env template
bun run pipeline set-key --name FAL_KEY   # Set a key (interactive)
bun run pipeline check-keys     # Check configured keys

Supported keys: FAL_KEY, GEMINI_API_KEY, GOOGLE_AI_API_KEY, OPENROUTER_API_KEY, ELEVENLABS_API_KEY, OPENAI_API_KEY, RUNWAY_API_KEY, HEYGEN_API_KEY, DID_API_KEY, SYNTHESIA_API_KEY

Unified JSON Output

All commands support --json for machine-readable output using a consistent envelope:

bun run pipeline generate-image -t "A cat" --json

Three possible envelope shapes:

See REFERENCE.md for full envelope docs.

3-Level Progressive Help (JSON)

The CLI provides structured help at three levels when using --help --json:

# Level 1: Root — list all commands, categories, global flags
bun run pipeline --help --json

# Level 2: Command — flags (required/optional), examples, usage
bun run pipeline generate-image --help --json

# Level 3: Parameter — type, enum values, default, description
bun run pipeline generate-image --help model --json

Each level returns a JSON envelope ({ "status": "ok", "data": { ... } }).

project.json — Agent-Readable Project State

Two CLI commands export the full project state as structured JSON:

# Minimal (~200 tokens): counts + settings only
bun run pipeline editor:project:info --project-id <id> --json

# Full (~2000 tokens): settings + media[] + subtitles[] + generated[] + exports[] + jobs[]
bun run pipeline editor:project:info --project-id <id> --full --json

# Dump to disk
bun run pipeline editor:project:export-state --project-id <id>

See editor-media.md for the full project.json schema.

Global Options

Key Source Files