Shotcut CLI
A stateful command-line interface for video editing, built on the MLT XML format. Designed for AI agents and power users who need to create and edit Shotcut projects without a GUI.
Prerequisites
- Python 3.10+
lxml(XML manipulation)click(CLI framework)
Optional (for interactive REPL):
prompt_toolkit
Optional (for rendering/media probing):
ffmpeg/ffprobemelt(MLT CLI)
Install Dependencies
pip install lxml click prompt_toolkit
How to Run
All commands are run from the agent-harness/ directory.
One-shot commands
# Show help
python3 -m cli.shotcut_cli --help
# Create a new project
python3 -m cli.shotcut_cli project new --profile hd1080p30 -o my_project.mlt
# Open a project and show info
python3 -m cli.shotcut_cli --project my_project.mlt project info
# JSON output (for agent consumption)
python3 -m cli.shotcut_cli --json --project my_project.mlt project info
Interactive REPL
python3 -m cli.shotcut_cli repl
python3 -m cli.shotcut_cli repl --project my_project.mlt
Inside the REPL, type help for all available commands.
Command Reference
Project
project new --profile <profile> [-o path] # Create new project
project open <path> # Open .mlt file
project save [path] # Save project
project info # Show project details
project profiles # List available profiles
project xml # Print raw MLT XML
Available profiles: hd1080p30, hd1080p60, hd1080p24, hd720p30, 4k30, 4k60, sd480p
Timeline
timeline show # Visual timeline overview
timeline tracks # List all tracks
timeline add-track --type <video|audio> [--name N] # Add track
timeline remove-track <index> # Remove track
timeline add-clip <file> --track <n> [--in tc] [--out tc] # Add clip
timeline remove-clip <track> <clip> [--no-ripple] # Remove clip
timeline move-clip <track> <clip> --to-track <n> # Move clip
timeline trim <track> <clip> [--in tc] [--out tc] # Trim clip
timeline split <track> <clip> --at <tc> # Split clip
timeline clips <track> # List clips on track
timeline add-blank <track> --length <tc> # Add gap
timeline set-name <track> <name> # Rename track
timeline mute <track> [--unmute] # Mute/unmute
timeline hide <track> [--unhide] # Hide/unhide
Filters
filter list-available [--category video|audio] # Browse filters
filter info <name> # Filter details + params
filter add <name> [--track n] [--clip n] [--param k=v ...] # Apply filter
filter remove <index> [--track n] [--clip n] # Remove filter
filter set <index> <param> <value> [--track n] [--clip n] # Set param
filter list [--track n] [--clip n] # List active filters
Transitions
transition list-available [--category video|audio] # Browse transitions
transition info <name> # Transition details + params
transition add <name> --track-a <n> --track-b <n> [--in tc] [--out tc] [--param k=v ...] # Add transition
transition remove <index> # Remove transition
transition set <index> <param> <value> # Set param
transition list # List active transitions
Available transitions: dissolve, wipe-left, wipe-right, wipe-down, wipe-up,
bar-horizontal, bar-vertical, diagonal, clock, iris-circle, crossfade
Compositing
composite blend-modes # List available blend modes
composite set-blend <track> <mode> # Set track blend mode
composite get-blend <track> # Get track blend mode
composite set-opacity <track> <value> # Set track opacity (0.0-1.0)
composite pip <track> <clip> [--x X] [--y Y] [--width W] [--height H] [--opacity O] # Picture-in-picture
Available blend modes: normal, add, multiply, screen, overlay, darken,
lighten, colordodge, colorburn, hardlight, softlight, difference,
exclusion, hslhue, hslsaturation, hslcolor, hslluminosity, saturate
Media
media probe <file> # Analyze media file
media list # List media in project
media check # Check all files exist
media thumbnail <file> -o <output> [--time tc] # Extract thumbnail
Export
export presets # List export presets
export preset-info <name> # Preset details
export render <output> [--preset name] [--overwrite] # Render project
Available presets: default, h264-high, h264-fast, h265, webm-vp9,
prores, gif, audio-mp3, audio-wav, png-sequence
Session
session status # Current session state
session undo # Undo last operation
session redo # Redo
session save # Persist session to disk
session list # List saved sessions
Timecode Formats
The CLI accepts these timecode formats anywhere a time value is expected:
| Format | Example | Meaning |
|---|---|---|
HH:MM:SS.mmm |
00:01:30.500 |
1 minute, 30.5 seconds |
HH:MM:SS:FF |
00:01:30:15 |
1 min 30 sec, frame 15 |
HH:MM:SS |
00:01:30 |
1 minute 30 seconds |
SS.mmm |
90.5 |
90.5 seconds |
| Frame number | 2715 |
Frame 2715 |
JSON Mode
Add --json before the subcommand for machine-readable output:
python3 -m cli.shotcut_cli --json --project p.mlt timeline clips 1
Running Tests
cd agent-harness
python3 -m pytest cli/tests/test_core.py -v
Example Workflow
# Create a project with two video tracks
python3 -m cli.shotcut_cli project new --profile hd1080p30 -o edit.mlt
python3 -m cli.shotcut_cli --project edit.mlt timeline add-track --type video --name "Main"
python3 -m cli.shotcut_cli --project edit.mlt timeline add-track --type audio --name "Music"
# Add clips (assuming media files exist)
python3 -m cli.shotcut_cli --project edit.mlt timeline add-clip intro.mp4 --track 1 --in 00:00:00.000 --out 00:00:05.000
python3 -m cli.shotcut_cli --project edit.mlt timeline add-clip main.mp4 --track 1 --in 00:00:00.000 --out 00:00:30.000
# Apply a brightness filter to the first clip
python3 -m cli.shotcut_cli --project edit.mlt filter add brightness --track 1 --clip 0 --param level=1.3
# View the timeline
python3 -m cli.shotcut_cli --project edit.mlt timeline show
# Save and render
python3 -m cli.shotcut_cli --project edit.mlt project save
python3 -m cli.shotcut_cli --project edit.mlt export render output.mp4 --preset h264-high --overwrite
Metadata
Release files for cli-anything-shotcut 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cli_anything_shotcut-1.0.0.tar.gz | 68.2 kB | Without provenance | Details for cli_anything_shotcut-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cli_anything_shotcut-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for cli_anything_shotcut-1.0.0-py3-none-any.whl |
Total release size: 144.0 kB
Release files / cli_anything_shotcut-1.0.0.tar.gz
| Download URL | cli_anything_shotcut-1.0.0.tar.gz |
|---|---|
| Size | 68.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ddcbe6f01d57b6462cfb67714bb1f940b4d20996f0165a8b8112f54762345872
|
|
BLAKE2b-256 checksum How to use checksums |
f23e0171d0a1db705e6c22be0dd1ba395b9b0a3b9465f1c87cbd7b5493869367
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Release files / cli_anything_shotcut-1.0.0-py3-none-any.whl
| Download URL | cli_anything_shotcut-1.0.0-py3-none-any.whl |
|---|---|
| Size | 75.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5be4c32167f08ad14c9cc022fbf1289bd6ce78fff13957979df402eae44d0793
|
|
BLAKE2b-256 checksum How to use checksums |
79513056af7f461f68217da6cb1e77484f11cc0249ee3e66749b17e24ea55db5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Security for cli-anything-shotcut 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.