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:

| Status | Shape | When | |--------|-------|------| | ok | { "status": "ok", "data": { ... } } | Command succeeded | | error | { "status": "error", "error": "msg", "code": "cmd:failed" } | Command failed | | pending | { "status": "pending", "jobId": "abc-123" } | Async job started |

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

| Flag | Short | Description | |------|-------|-------------| | --output-dir | -o | Output directory (default: ./output) | | --model | -m | Model key | | --json | | Output as JSON | | --quiet | -q | Suppress progress | | --verbose | -v | Debug logging | | --stream | | JSONL progress events on stderr | | --help | -h | Print help | | --session | | Session mode: read commands from stdin | | --skip-health | | Skip editor health check | | --no-capability-check | | Skip per-request capability warnings |

Key Source Files

| Component | File | |-----------|------| | CLI entry point | electron/native-pipeline/cli/cli.ts | | Command router | electron/native-pipeline/cli/cli-runner/runner.ts | | Command registry (core) | electron/native-pipeline/cli/command-registry.ts | | Command registry (editor) | electron/native-pipeline/cli/command-registry-editor.ts | | Command registry types | electron/native-pipeline/cli/command-registry-types.ts | | JSON output helpers | electron/native-pipeline/cli/json-output.ts | | project.json types | electron/native-pipeline/cli/project-json-types.ts | | project.json builder | electron/native-pipeline/cli/project-json-builder.ts | | Editor dispatch | electron/native-pipeline/cli/cli-handlers-editor.ts | | Admin handlers | electron/native-pipeline/cli/cli-handlers-admin.ts | | Media handlers | electron/native-pipeline/cli/cli-handlers-media.ts | | ViMax handlers | electron/native-pipeline/cli/vimax-cli-handlers.ts | | Remotion handler | electron/native-pipeline/cli/cli-handlers-remotion.ts | | Moyin handler | electron/native-pipeline/cli/cli-handlers-moyin.ts | | Key manager | electron/native-pipeline/key-manager.ts |