Commands
Serializable, zod-validated project mutations in @mcut/timeline.
Commands are the only way mcut project state changes. They live in
@mcut/timeline and are designed to be serializable, undoable, and safe to expose
as tools.
Command shape
Every command is an object with a type plus command-specific payload fields.
{
"type": "addTrack",
"name": "Overlays"
}The engine validates payloads with zod and rejects edits that violate project invariants such as unknown ids, invalid element shapes, or track overlaps.
Command table
Commands live in one closed table, commandDefinitions in
packages/timeline/src/commands.ts, and BuiltinCommand is the union of every
entry. The table backs:
listCommands()for command definitions.listToolDefinitions()for MCP-shaped tool definitions.parseCommand(value)for turning untrusted JSON into aBuiltinCommand.applyCommand(project, command)for pure command application.EditorEngine.dispatch(command)for engine-managed application with undo state.
Inspect schemas
Use the CLI to inspect the current command set:
bunx @mcut/cli commands --json
bunx @mcut/cli commands --name addElementAgents should inspect schemas instead of guessing payloads.
Major command groups
| Group | Examples |
|---|---|
| Project and tracks | updateProject, addTrack, removeTrack, renameTrack, setTrackFlags, reorderTrack, compactTrackGaps, compactTimelineGaps |
| Assets | addAsset, updateAsset, removeAsset |
| Elements | addElement, removeElement, updateElement, moveElement, trimElement, splitElement, rippleDelete, removeRanges |
| Captions and derived clips | applyCaptions, detachAudio, applyThumbnail |
| Keyframes | setKeyframe, removeKeyframe, moveKeyframe, setKeyframeEasing, clearKeyframes |
| Zoom regions | addZoomRegion, updateZoomRegion, removeZoomRegion |
| Effects and presets | effect stack commands, animation presets, property presets |
| Multicam | multicam creation, layout, cut, and source-selection commands |
| Audio and markers | linked audio helpers, timeline marker add/update/remove commands |
Agent guidance
Use commands when the desired mutation is exact. Use operators when the desired edit depends on current selection, playhead, track context, or UI behavior.