<img width="1672" height="941" alt="image" src="https://github.com/user-attachments/assets/86fa31b1-9229-484a-9ce8-6314d4015340" />

davinci-resolve-cli (dvr)

A CLI for DaVinci Resolve 18+ — project / media / render / timeline control for humans and AI agents.

Demo

$ dvr doctor --format json | jq '{version, edition, bridgeStatus}'
{
  "version": "19.1.4.11",
  "edition": "Studio",
  "bridgeStatus": "ok"
}

$ dvr project current --format json
{
  "name": "Untitled Project",
  "timelineCount": 1,
  "framerate": 24.0,
  "resolution": { "width": 3840, "height": 2160 }
}

$ dvr render presets --format json | head -3
[
  "H.264 Master",
  "ProRes 422 HQ"

$ dvr timeline marker add --at 00:00:01:00 --note "review" --color Green --format json
{ "ok": true, "frame": 24, "timecode": "00:00:01:00" }

$ dvr mcp   # ← then any MCP client (stdio) can call 20 tools

An animated demo will replace this snapshot once vhs docs/demo.tape can be run on macOS 15 (the tape script and docs/demo.tape source are already in the repo).

Install

pipx install davinci-resolve-cli

Requires DaVinci Resolve 18+ already installed (Studio recommended). macOS first; Windows/Linux follow.

Quickstart

# Health check
dvr doctor

# Project ops
dvr project list
dvr project current

# Media batch
dvr media import ~/footage --recursive --bin "Day1"

# Render (async)
JOB=$(dvr render submit --preset "H.264 Master" --timeline cur --output ~/out.mp4 --format json | jq -r .jobId)
dvr render wait "$JOB"

# Timeline scripted edits
dvr timeline marker add --at 01:00:05:00 --note "review"

Capabilities at a glance

Domain	Subcommands	What it does
doctor	—	Diagnose the Resolve bridge environment (version, Studio / Free, API path, issues)
project	list / current / open / new / close / save / export / import	Project library CRUD
media	import / list / tag	Media-pool batch ops — recursive import, per-bin lookup, 16 named flag colors, partial-failure reporting
render	presets / submit / status / list / wait / cancel	Async render queue. submit returns a jobId immediately; wait blocks until terminal (completed / failed / cancelled)
timeline	list / current / open / new / delete / clips / cut* / move*<br>marker add / delete / list	Timeline CRUD + marker ops. *cut and move go through the WI bridge but currently emit placeholder behavior because Resolve has no public razor / clip-move API — see docs/wi-research.md.
mcp	—	Start a stdio MCP server exposing 20 tools (one per CLI verb), each with a JSON-Schema'd inputSchema
subtitle	import / export	Round-trip .srt / .vtt between disk and the timeline subtitle track
config	show / init	TOML-driven defaults; <cwd>/.dvr/config.toml and ~/.dvr/config.toml merged, CLI flag > project > user > built-in
install-wi	--uninstall / --force	Deploy / remove the Workflow Integration plugin used by timeline cut and timeline move

Conventions across every command:

• --format json|yaml|table — JSON by default in non-TTY, table (rich) in TTY, override via DVR_OUTPUT
• Structured errors on stderr — {"errorCode", "message", "hint"}, stable codes (resolve_not_running, validation_error, not_found, api_call_failed, wi_unavailable, …)
• --dry-run on every mutating command — prints the planned actions without touching Resolve
• Exit codes: 0 ok, 1 user error, 2 Resolve unavailable, 3 API call failed

Output formats

context	default
TTY	table (rich)
pipe / non-TTY	json

Override with --format json|yaml|table or DVR_OUTPUT=yaml.

AI Agent

dvr ships two complementary AI-agent integration paths.

1. Skill file (SKILL.md)

A SKILL.md packaged with the wheel; auto-discovered by skill systems that scan installed packages. Five worked example prompts:

• "Render the current timeline as 1080p mp4"
• "List clips imported today and tag them green"
• "Wait for render job X and tell me when it finishes"
• "Check if Resolve is ready"
• "Tag all clips in Day1 bin as Green for review"

2. MCP server (dvr mcp)

Standard stdio MCP server exposing 20 tools across doctor / project.* / media.* / render.* / timeline.* namespaces. Any MCP-aware AI client can wire it up:

// .mcp.json or your client's MCP server config
{
  "mcpServers": {
    "davinci-resolve": {
      "command": "dvr",
      "args": ["mcp"]
    }
  }
}

Tool errors are returned as structured JSON {"errorCode", "message", "hint"} matching the CLI's stderr contract — same error codes (resolve_not_running, validation_error, not_found, etc.) so an agent can branch on them deterministically.

Verify the server is reachable:

dvr mcp   # blocks, reads stdin/writes stdout per MCP spec

Architecture

flowchart LR
    Human["Human<br/>(terminal)"]
    Agent["AI agent<br/>(MCP client)"]
    CLI["dvr CLI"]
    MCP["dvr mcp<br/>(stdio)"]

    Boot["bootstrap.py"]
    DVRScript["DaVinciResolveScript"]
    Resolve["DaVinci Resolve 18+"]

    WIServer["wi_client.py<br/>(localhost:50420)"]
    WIPlugin["WI plugin<br/>(JS, inside Resolve)"]

    Jobs["~/.dvr/jobs.json"]

    Human -->|argv| CLI
    Agent -->|tool calls| MCP
    MCP -->|same helpers| CLI
    CLI --> Boot --> DVRScript --> Resolve
    CLI -->|render jobs| Jobs
    CLI -->|cut/move<br/>JSON-RPC| WIServer
    WIPlugin -->|poll /inbox<br/>POST /result| WIServer
    WIPlugin --> Resolve

Five command domains, two transports (CLI + MCP), one bridge (DaVinciResolveScript), one escape hatch for ops the Python API doesn't cover (Workflow Integration). Full write-up in docs/architecture.md.

Compatibility

OS	Status
macOS (Apple Silicon / Intel)	✅ primary, end-to-end verified
Windows	✅ unit + CI tested (real-Resolve smoke pending community feedback)
Linux	✅ unit + CI tested (Resolve Studio Linux only)

Resolve	Status
18.x Studio	✅
18.x Free	⚠️ partial (render encoders limited)
17.x or older	❌ unsupported

Cookbook

Five end-to-end recipes covering the most common workflows. Each is a copy-paste shell snippet that assumes DaVinci Resolve 18+ Studio is running and a project is open.

1. Render the current timeline as 1080p H.264 mp4

# Preflight: make sure the bridge is healthy
dvr doctor --format json | jq -e '.bridgeStatus == "ok"' >/dev/null || { echo "Resolve not ready"; exit 2; }

# Pick the first preset whose name contains "H.264"
PRESET=$(dvr render presets --format json | jq -r '.[] | select(test("H\\.264"; "i"))' | head -1)

# Submit (async — returns immediately), then block until done
JOB=$(dvr render submit --preset "$PRESET" --timeline cur --output ~/Renders/out.mp4 --start --format json | jq -r .jobId)
dvr render wait "$JOB"   # progress to stderr, terminal status to stdout

2. Import a SD card's footage into per-date bins

# Assumes ~/footage/<YYYY-MM-DD>/ structure
for day_dir in ~/footage/*/; do
  day=$(basename "$day_dir")
  dvr media import "$day_dir" --bin "$day" --recursive --format json | jq '.imported | length' \
    | xargs -I{} echo "imported {} clips into '$day'"
done

3. Tag every clip in a bin as "Green" for review (skipping ones already tagged)

BIN="Day1"
IDS=$(dvr media list --bin "$BIN" --format json \
  | jq -r '.[] | select(.flags | index("Green") | not) | .id')
[ -n "$IDS" ] && dvr media tag $IDS --color Green --format json

4. Drop chapter markers from a CSV file (timecode, label)

# chapters.csv:
#   00:00:00:00,intro
#   00:01:30:00,demo
#   00:04:15:00,outro
while IFS=, read -r tc label; do
  dvr timeline marker add --at "$tc" --name "$label" --color Sky --format json >/dev/null
done < chapters.csv

dvr timeline marker list --format json | jq '.[] | "\(.timecode) → \(.name)"'

5. AI agent: render via MCP server

Wire dvr mcp into any MCP-aware client (most desktop AI assistants now support MCP — check your client's docs for the right config file path):

// ~/.config/<client>/mcp.json
{ "mcpServers": { "davinci-resolve": { "command": "dvr", "args": ["mcp"] } } }

Then ask the agent:

"Render the currently open timeline as 1080p H.264, save it to ~/out.mp4, and tell me when it's done."

The agent will call doctor → render.presets → render.submit(start=true) → render.wait automatically. Tool errors come back as structured {errorCode, message, hint} so the agent can branch on resolve_not_running / validation_error / etc. deterministically.

Configuration

dvr reads two optional TOML files and merges them with this precedence (highest wins):

1. CLI flag — per command, always wins
2. <cwd>/.dvr/config.toml — project-local; commit it to your repo so your team shares the same defaults
3. ~/.dvr/config.toml — user-global; your personal preferences across all projects
4. Built-in defaults

Initialize a commented sample in the current project:

dvr config init

See exactly which layer every effective value came from:

dvr config show --format json | jq '.sources'

Initial supported fields (more can be added incrementally without breaking changes):

[defaults]
output_format = "json"     # default --format for table-capable commands
bin = "Master"             # default --bin for media import / list
preset = "H.264 Master"    # default --preset for render submit
marker_color = "Blue"      # default --color for timeline marker add
marker_duration = 1

Troubleshooting

<details> <summary><b>dvr doctor reports resolve_not_running but Resolve is open</b></summary>

Make sure:

1. A project is open inside Resolve (the splash / project picker doesn't count).
2. Preferences → System → General → External scripting using is set to Local. The default is None; Local is required for DaVinciResolveScript to accept connections.
3. You're on Resolve 18 or newer. dvr doctor will tell you the detected version under version. </details>

<details> <summary><b>Free vs Studio — what works on Free?</b></summary>

dvr doctor reports your edition in the edition field. On Free:

• ✅ All project, media, timeline marker * commands work
• ⚠️ render submit works but some preset codecs (DNxHR, ProRes 4444, etc.) are Studio-only — the job will queue but fail at encode time
• ❌ dvr install-wi deploys the plugin but Workflow Integrations require Resolve Studio at runtime, so timeline cut / move will return wi_unavailable on Free </details>

<details> <summary><b>pipx install fails with No matching distribution found for mcp>=1.0</b></summary>

Your Python is 3.9 or older. dvr 0.2.1+ requires Python 3.10+ because the mcp SDK does. Check with python --version. If your system Python is too old, install a newer one (pyenv install 3.12, brew install python@3.12, or use Homebrew Cask). </details>

<details> <summary><b>Windows: dvr doctor can't find DaVinciResolveScript</b></summary>

Resolve's default install path on Windows is %PROGRAMDATA%\Blackmagic Design\DaVinci Resolve\Support\Developer\Scripting\. If you installed Resolve to a custom location, set these two env vars before running dvr:

set RESOLVE_SCRIPT_API=<your-path>\Support\Developer\Scripting
set RESOLVE_SCRIPT_LIB=<your-path>\fusionscript.dll

dvr doctor --format json shows the resolved apiPath and libPath — useful to confirm what we tried. </details>

<details> <summary><b>I ran dvr install-wi but the bridge doesn't show up in Resolve's Workspace menu</b></summary>

1. Restart Resolve. Workflow Integrations are scanned at launch.
2. Check you're on Resolve Studio — WI is Studio-only.
3. macOS: the plugin must land at ~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Workflow Integration Plugins/dvr-cli-bridge/. dvr install-wi --format json prints the destination — verify the path exists and contains manifest.xml / index.html / server.js.
4. After enabling under Workspace → Workflow Integrations, a small panel should pop up showing "Polling localhost:50420…". If you don't see it, check Resolve's console.log (Help → Logs). </details>

Development

pip install -e ".[dev]"
pytest                              # unit only
pytest -m integration               # requires Resolve running

License

MIT