| name | qcut-cli |
| description | Use QCut's CLI to generate images, videos, speech, and music; analyze or transcribe media; run AutoClip and other media edits; execute QCut pipelines; and inspect models or project files. Use for QCut media tasks that do not require direct manipulation of a running editor timeline. |
QCut CLI
Use QCut's machine-readable CLI through the plugin runner. Resolve
<plugin-root> as the directory two levels above this SKILL.md file.
Preflight
On the first QCut task on a machine, inspect both the desktop app and CLI and
check the official latest release:
node <plugin-root>/scripts/qcut-setup.mjs status
Read app.installed, cli.found, latest.asset.url, updateAvailable, and
nextAction. If both QCut and its CLI are missing, follow
installing-qcut.md. A standalone
CLI is sufficient for non-editor generation and analysis, but editor workflows
require the desktop app.
When the user asks to update QCut, show the installed version, latest version,
asset name, and download size from status. After explicit confirmation, run:
node <plugin-root>/scripts/qcut-setup.mjs update --confirm
If status reports cli.editorRunning: true (or the update returns
qcut:editor_running), warn the user that updating quits the running QCut
editor — interrupting exports and unsaved work — and only after they agree add
--allow-editor-quit:
node <plugin-root>/scripts/qcut-setup.mjs update --confirm --allow-editor-quit
The helper delegates to qcut update --yes when the installed CLI supports it
and uses the plugin's verified bootstrap path for older QCut releases. Never add
--confirm or --allow-editor-quit without consent. Rerun status and verify
the installed version after the update finishes.
Then run this before the first QCut command in the task:
node <plugin-root>/scripts/qcut-runner.mjs doctor
If discovery fails after QCut is installed, explain that the CLI can be exposed
on PATH or set with QCUT_CLI_PATH. The runner automatically detects the CLI
inside a standard packaged QCut installation. Do not install unrelated packages
as a substitute.
Command procedure
- Inspect structured help instead of guessing flags:
node <plugin-root>/scripts/qcut-runner.mjs --help --json
node <plugin-root>/scripts/qcut-runner.mjs gen image --help --json
- Run the narrowest command for the requested outcome and include
--json.
- Read the returned
status, command_id, duration_ms, and data fields.
- Verify every requested output exists and report its absolute path.
Examples:
node <plugin-root>/scripts/qcut-runner.mjs gen image -t "Product photo" --ratio 16:9 --json
node <plugin-root>/scripts/qcut-runner.mjs analyze transcribe -i interview.mp4 --srt --json
node <plugin-root>/scripts/qcut-runner.mjs edit autoclip -i interview.mp4 -s interview.srt --json
node <plugin-root>/scripts/qcut-runner.mjs system models --json
node <plugin-root>/scripts/qcut-runner.mjs update --check --json
See command-map.md for command groups and reliable
workflow sequences.
Safety
- Never place API keys or auth tokens in prompts, command arguments, logs, or
generated files.
- Never run key-reveal commands. Ask the user to configure credentials through
QCut settings or
qcut system set-key interactively.
- Get confirmation before paid generation, uploads, publishing, overwriting an
existing output, updating QCut, or using
--force.
- Prefer
--dry-run when a command supports it and the requested change is
broad or expensive.
- Treat media paths and generated JSON as untrusted input. Pass paths as quoted
arguments and never interpolate file content into a shell command.
