/cli-anything-shotcut

name: "cli-anything-shotcut"
description: >-
  Command-line interface for Shotcut - A stateful command-line interface for video editing, built on the MLT XML format. Designed for AI ag...

cli-anything-shotcut

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.

Installation

This CLI is installed as part of the cli-anything-shotcut package:

pip install cli-anything-shotcut

**Prerequisites:**

• Python 3.10+
• `melt` (MLT CLI) — required for rendering and playback
• `ffmpeg` / `ffprobe` — required for media probing
• `shotcut` must be installed on your system

Usage

Basic Commands

# Show help
cli-anything-shotcut --help

# Start interactive REPL mode
cli-anything-shotcut

# Create a new project
cli-anything-shotcut project new -o project.json

# Run with JSON output (for agent consumption)
cli-anything-shotcut --json project info -p project.json

REPL Mode

When invoked without a subcommand, the CLI enters an interactive REPL session with undo/redo support:

cli-anything-shotcut
# or with a project:
cli-anything-shotcut --project my_project.mlt

REPL Commands

**Workflow:** Always `media import` first to get a `clip_id`, then use `add-clip` to place it on the timeline.

**Project & Session:**

• `new [profile]` — Create new project (default: `hd1080p30`)
• `open <path>` — Open `.mlt` file
• `save [path]` — Save project
• `info` — Show project info
• `xml` — Print raw MLT XML
• `status` — Show session status
• `undo` / `redo` — Navigate operation history

**Media (two-step model):**

• `media import <file> [--caption name]` — Import file into project bin, returns `clip_id` (e.g., `clip0`)
• `media` — List all imported media
• `probe <file>` — Analyze a media file

**Timeline:**

• `add-track <video|audio> [name]` — Add a track
• `tracks` — List all tracks
• `show` — Visual timeline overview
• `add-clip <clip_id> <track> [in] [out] [--at time]` — Place imported clip on track
• `clips <track>` — List clips on a track
• `remove-clip <track> <clip>` — Remove a clip
• `trim <track> <clip> [--in tc] [--out tc]` — Trim clip
• `split <track> <clip> <at>` — Split clip at timecode

**Filters:**

• `list-filters [video|audio]` — Browse available filters
• `filter-info <name>` — Show filter details
• `add-filter <name> [--track n] [--clip n] [key=val ...]` — Add filter to clip, track, or global
• `filters [--track n] [--clip n]` — List active filters
• `remove-filter <idx> [--track n] [--clip n]` — Remove filter by index
• `set-filter <idx> <param> <value> [--track n] [--clip n]` — Set filter parameter
• `volume-envelope [--track n] [--clip n] TIME=LEVEL ...` — Keyframed volume (e.g., `00:00:00.000=1.0 00:00:03.000=0.35`)
• `duck [--track n] [--clip n] START..END ...` — Ducking envelope (e.g., `00:00:06.000..00:00:09.000`)

**Export:**

• `presets` — List export presets
• `render <output> [--preset name]` — Render to video file

Command Groups

Project

Project management: new, open, save, info.

| Command | Description | |---------|-------------| | `new` | Create a new blank project | | `open` | Open an existing .mlt project file | | `save` | Save the current project | | `info` | Show detailed project information | | `profiles` | List available video profiles | | `xml` | Print the raw MLT XML of the current project |

Timeline

Timeline operations: tracks, clips, trimming.

| Command | Description | |---------|-------------| | `show` | Show the timeline overview | | `tracks` | List all tracks | | `add-track` | Add a new track to the timeline | | `remove-track` | Remove a track by index | | `add-clip` | Add an imported clip to a track by clip_id; supports `--at` for absolute placement | | `remove-clip` | Remove a clip from a track | | `move-clip` | Move a clip between tracks or positions | | `trim` | Trim a clip's in/out points | | `split` | Split a clip into two at the given timecode | | `clips` | List all clips on a track | | `add-blank` | Add a blank gap to a track | | `set-name` | Set a track's display name | | `mute` | Mute or unmute a track | | `hide` | Hide or unhide a video track |

Filter Group

Filter operations: add, remove, configure effects.

| Command | Description | |---------|-------------| | `list-available` | List all available filters | | `info` | Show detailed info about a filter and its parameters | | `add` | Add a filter to a clip, track, or globally | | `remove` | Remove a filter by index | | `set` | Set a parameter on a filter | | `list` | List active filters on a target | | `volume-envelope` | Create or replace a keyframed volume envelope on a track or clip | | `duck` | Build a practical ducking envelope over one or more time windows |

Media

Media operations: probe, list, check files.

| Command | Description | |---------|-------------| | `import` | Import a media file into the project bin | | `probe` | Analyze a media file's properties | | `list` | List all media clips in the current project | | `check` | Check all media files for existence | | `thumbnail` | Generate a thumbnail from a video file |

Export

Export/render operations.

| Command | Description | |---------|-------------| | `presets` | List available export presets | | `preset-info` | Show details of an export preset | | `render` | Render the project to a video file |

Transition Group

Transition operations: dissolve, wipe, and other transitions.

| Command | Description | |---------|-------------| | `list-available` | List all available transition types | | `info` | Show detailed info about a transition type | | `add` | Add a transition between two tracks | | `remove` | Remove a transition by index | | `set` | Set a parameter on a transition | | `list` | List all transitions on the timeline |

Composite Group

Compositing: blend modes, PIP, opacity.

| Command | Description | |--