DaVinci Resolve CLI

Install

pipx install davinci-resolve-cli

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

Quickstart

```bash

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).

00:01:30:00,demo

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

davinci-resolve-cli (`dvr`)

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

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>