Qcut Video Edit

Run QCut's native TypeScript pipeline CLI for AI content generation, video analysis, transcription, YAML pipelines, ViMax agentic video production, and proje...

Security Scan

The skill's documentation and runtime instructions describe controlling a local QCut CLI/desktop (bun, electron, qcut-pipeline) and reading/writing local config and other agent skill files, but the skill metadata declares no required binaries, env vars, or install steps — those mismatches and the ability to reveal local API keys and read other agent files are concerning and should be clarified before installing.

Purpose & Capability

The skill claims to run QCut's native TypeScript pipeline and editor HTTP automation (which legitimately requires local binaries like bun, a qcut-pipeline binary, electron, and curl). However the registry metadata lists no required binaries, no required env vars, and no install steps. That is an incoherence: documentation expects tools that are not declared as required.

Instruction Scope

The SKILL.md instructs the agent to run local shell commands (curl to http://127.0.0.1:8765, bun run build, bun run electron, bun run pipeline commands), read/write ~/.qcut/.env, dump project state to disk, and locate other agent files (e.g., .agents/skills/remotion-best-practices/SKILL.md). These actions go beyond simple CLI usage: they can start background processes, read local config and other skill files, and (via pipeline key commands) potentially reveal secret values if a user runs 'get-key --reveal' or similar. The instructions also give broad discretion to import/export files and interact with the editor API — not strictly scoped to a single narrow task.

Install Mechanism

This is an instruction-only skill with no install spec and no code files, so there's no installer or external binary being downloaded by the skill package itself. That reduces risk from remote code fetch, but the runtime instructions still direct running local build/execution commands (bun/electron).

Credentials

The docs reference many API keys stored at ~/.qcut/.env (FAL_KEY, GEMINI_API_KEY, OPENAI_API_KEY, etc.) and include commands to set/check/reveal keys, but the skill metadata declares no required environment variables or primary credential. This is a mismatch: the skill expects to manage/inspect local secrets but doesn't declare any credential access. Additionally, commands can expose whether keys are configured and (with --reveal) full values — a potential vector for accidental secret disclosure if used carelessly.

Persistence & Privilege

The skill does not set always:true and has no install mechanism that would embed it persistently. It does instruct launching local processes (bun run electron &), but that is a normal behavior for a CLI controlling a local desktop app and not a privilege escalation of the skill package itself.

What to consider before installing

What to consider before installing or running this skill: - The SKILL.md expects you to have and run local developer tools (bun, electron) and the qcut pipeline. The skill metadata does not declare those required binaries — confirm you have the intended QCut application and that these commands are safe in your environment. - The instructions access local configuration (~/.qcut/.env) and include commands to set and reveal API keys. Never run commands that reveal secrets unless you explicitly trust the environment and understand where output goes. - The skill suggests reading other agent skill files (e.g., .agents/skills/...), which means it expects access to your agent's filesystem. If you do not want a skill to read other skill files or local configs, avoid running these commands or run them in an isolated environment (VM/container). - Building and launching (bun run build; bun run electron &) executes code on your machine. Treat that like running any unreviewed program — inspect upstream source or run in an isolated test environment first. - Ask the publisher for clarifications: a list of explicit required binaries, which local paths will be read/written, and why reading .agents/skills is necessary. Prefer installing only from a trusted homepage/source; this package has 'Source: unknown' and no homepage, which reduces provenance confidence. - If you need to proceed, run commands manually rather than letting an agent run them autonomously, and avoid using any --reveal or other flags that expose full secret values.

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