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

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

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

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

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

Development

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

License

MIT