final-cut-pro-cli

Agent-friendly CLI for Apple Final Cut Pro on macOS.

final-cut-pro-cli gives Final Cut Pro a command-line surface that scripts and AI agents can call. It covers the rough-cut preparation workflow around Libraries, Events, Projects, Media, and Timeline clips, then opens the generated Library in Final Cut Pro for manual finishing or later automation.

Positioning

• Target users: professional editors who need scripted batch workflows, and automation / AI-editing engineers building agent workflows.
• Core scenario: assist professional editing workflows by exposing FCP operations as atomic, composable CLI commands.
• Non-goals: no built-in AI features; no attempt to replace the Final Cut Pro UI.

Platform Requirements

Item	Requirement
Operating system	macOS only
Final Cut Pro	10.7+
FCPXML schema	1.11+
Python	3.10+

The CLI performs startup checks and exits with PLATFORM_UNSUPPORTED, FCP_NOT_INSTALLED, or FCP_VERSION_TOO_OLD when the environment is not supported.

Installation

pip install final-cut-pro-cli

Command Surface (v0.1 MVP)

Library (FCP-specific)

fcp library new <name> [--path <dir>]      # Create and register a .fcpbundle
fcp library list                            # List registered Libraries
fcp library open <name|path>                # Open a Library in Final Cut Pro

Event (FCP-specific)

fcp event new <name> --library <ref>
fcp event list --library <ref>

Project (aligned with dr-cli where possible)

fcp project new <name> --library <ref> --event <ref> [--resolution 1920x1080] [--fps 30]
fcp project list --library <ref> [--event <ref>]
fcp project info <name> --library <ref> --event <ref>

Media

fcp media import <video>... --library <ref> --event <ref>

Clip Editing

fcp clip add --library <ref> --event <ref> --project <name> --asset <asset-id> [--duration <dur>]
fcp clip cut --library <ref> --event <ref> --project <name> --at <timecode>
fcp clip move --library <ref> --event <ref> --project <name> --clip <index> --to <timecode>
fcp clip trim --library <ref> --event <ref> --project <name> --clip <index> --start <tc> --end <tc>
fcp clip delete --library <ref> --event <ref> --project <name> --clip <index>

Subtitle (Reserved Command Group)

fcp subtitle add <text> --at <tc> --duration <dur>
fcp subtitle import <srt-file>

v0.1 only reserves the subtitle command group. It does not write subtitle or title content yet. Full subtitle/title authoring is planned for a later release.

Export

fcp export submit <project-name> --preset <name> --output <path>

v0.1 note: Final Cut Pro 11.1.1's scripting dictionary does not expose an export, share, or render command. fcp export submit keeps the command surface aligned with dr-cli, but returns a structured export_unavailable error instead of pretending to export via UI scripting. MP4 export remains a manual FCP UI step for now, or a future Compressor / external rendering research track. export status is reserved for future asynchronous export support and is not implemented in v0.1.

MCP Server Mode

fcp mcp serve            # Start the stdio MCP server for Cursor / Claude Code

Example configs:

• Cursor: examples/cursor-mcp.json
• Claude Desktop: examples/claude-desktop-mcp.json

MCP tools use dotted names such as library.new, event.list, project.info, clip.cut, and export.submit. Tools reuse the same CLI command path and default to --json, so MCP return values match shell output.

Global Options

• --json - emit structured output for all commands, including errors.
• --verbose - print detailed FCPXML changes and AppleScript calls.

--library, --event, and --project are command-level scope parameters, not global flags. v0.1 does not read the current active Library from Final Cut Pro; agent callers should pass the target Library / Event / Project explicitly.

Alignment With davinci-resolve-cli

Command layer	Aligned with dr-cli	Notes
Library	No	FCP-specific; dr-cli has no Library concept.
Event	No	FCP-specific; dr-cli has no Event concept.
Project / Media / Clip / Export	Mostly	FCP adds explicit Library / Event scope.
Subtitle	Reserved	v0.1 keeps the command group for later parity.

See docs/dr-cli-alignment.md for details.

Error Codes

Exit code ranges:

Range	Meaning
0	Success
1-19	User input errors, such as invalid arguments or missing files
20-39	FCP state errors, such as FCP not running or Library not open
40-59	Long-running operation errors, such as AppleScript timeout or export failure
60+	Internal errors, such as FCPXML parse failure or AppleScript exception

See docs/error-codes.md for details.

Architecture

The project uses a src/ layout and mirrors davinci-resolve-cli where the domain model overlaps:

src/fcp/
├── cli.py              # Typer entry point: main_entry()
├── bootstrap.py        # Platform / FCP version preflight checks
├── errors.py           # Error code ranges and FcpCliError
├── output.py           # JSON / rich output handling
├── timecode.py         # Timecode parsing with dr-cli-compatible semantics
├── fcp_app.py          # AppleScript bridge, analogous to dr-cli/resolve.py
├── fcpxml/             # FCPXML parsing and writing, the main edit path
├── commands/
│   ├── library.py      # FCP-specific
│   ├── event.py        # FCP-specific
│   ├── project.py      # Aligned with dr-cli/project.py
│   ├── media.py        # Aligned with dr-cli/media.py
│   ├── timeline.py     # Aligned with dr-cli/timeline.py
│   ├── subtitle.py     # Reserved for planned dr-cli v0.3 parity
│   ├── export.py       # Aligned with dr-cli/render.py; FCP calls it Export
│   ├── doctor.py       # Aligned with dr-cli/doctor.py
│   ├── completion.py   # Aligned with dr-cli/completion.py
│   └── mcp_cmd.py      # Aligned with dr-cli/mcp_cmd.py
├── jobs/               # Reserved for future export / MCP long-running jobs
├── mcp/                # MCP server implementation
└── schemas/            # JSON schemas using dr-cli-compatible camelCase fields

Design Constraints

• FCPXML-first editing - content edits for Library, Event, Project, Media, Clip, and future Subtitle features go through FCPXML file operations and do not require Final Cut Pro to be running.
• AppleScript only for runtime triggers - v0.1 uses AppleScript for library open and FCP Library inspection only. The current FCP scripting dictionary does not expose export/share automation.
• No UI scripting - the project does not use System Events, coordinate clicks, key codes, keystrokes, or AXUIElement automation. Tests scan for and reject these fragments.

Development

# Install development dependencies
pip install -e ".[dev]"

# Unit tests
pytest tests/fcpxml tests/cli

# End-to-end test requiring macOS + FCP 10.7+
FCP_E2E_OPEN_REAL_FCP=1 \
PYTHONPATH=/private/tmp/fcp-cli-pytest-stubs:src \
pytest tests/e2e/test_real_fcp_open.py -m integration -q

See test-cases.md for the test checklist and docs/e2e-troubleshooting.md for E2E troubleshooting.

Roadmap

• v0.1 - rough-cut preparation MVP: library/event/project/media import, clip add/cut/library open, explicit export_unavailable fallback, and MCP server.
• v0.2 - dr-cli v0.2 alignment: cross-platform FCPXML operations where possible, recipe mode, and batch media glob/import helpers.
• v0.3 - dr-cli v0.3 alignment: enhanced razor-cut workflows, MCP HTTP, complete subtitle support, and config files.

Sister Project

• davinci-resolve-cli - CLI for DaVinci Resolve from the same team, with aligned command surfaces below the Project layer.

License

MIT