Update the output format for various asset and folder commands to ensure JSON Lines are emitted on stdout, providing a consistent structure across commands. Enhance error handling to ensure that unknown ids or invalid inputs fail the entire command, improving user feedback and command reliability. This change streamlines the user experience and aligns with the fail-fast convention for batch commands.
7.8 KiB
CLI reference
dapi drives a running Diffusion Studio instance over a local socket. Every command except open and fonts needs the app running; launch it with dapi open (add -b for headless).
Conventions
- stdout is JSON. Single results are one JSON value; collections and batch results are JSON Lines (one object per line, no surrounding array).
mountandnode insertprint nothing on success. - stderr is for humans: error messages and progress spinners.
- Exit codes:
0on success,1on any error. - Unix names are canonical:
ls,rm,cp,mv,grep. The English forms (list,remove,duplicate,move) are aliases, andgetis an alias for everyls. - Group aliases:
selection→sel,node→n,project→p,asset→a,folder→fld,context→ctx. - Batch commands are fail-fast (
node rm,node patch,asset add, …): one invalid input fails the whole command with a single stderr message and exit1. Ids are validated before anything changes, so a failedrm/mv/cpchanges nothing; there are no per-item partial results.
Time values
Wherever a command takes a time, three formats are accepted (frames are at 30 fps):
| Format | Example | Meaning |
|---|---|---|
| number | 2.2 |
seconds |
"<n>f" |
"45f" |
frames |
| clock | "02:30", "01:02:30" |
MM:SS or HH:MM:SS |
Times in output are plain seconds, except in node ls, whose raw records use engine units (frames, packed 0xRRGGBB colors, dB).
App
open
dapi open [target] [-b, --background]
Launches the app, or opens a target: a file, a diffusion:// deep link, or a folder, which creates a project from the folder's media (or switches to the one created earlier; see Getting started). --background launches with no window, for headless use. The only command that doesn't need the app already running (besides fonts).
whoami
Prints the signed-in account { id, email, provider }, or null.
context
Prints the open project's essentials: project id and name, entity count, scenes with sizes, the active scene, the playhead position (frames), and available font families. Call it first.
Composing
mount
dapi mount (<path> | --code <str>)
Compiles a Solid JSX module and mounts its rendered roots into the document. Re-mounting rebuilds keyed roots in place, like reloading a webpage. Declared generative assets are produced during the mount, which blocks until they land. With --code, a bare JSX expression is wrapped into a module automatically. See Writing compositions.
node insert
dapi node insert <parentId> (<path> | --code <str>) [-i, --index <N>]
Same pipeline as mount, but inserts the rendered roots as children of an existing entity instead of mounting document roots. Roots take no key; every run inserts fresh nodes. --index sets the position among the parent's children (node roots only). Also how you extend sub-entities, e.g. adding a stop to a gradient:
dapi node insert <paintId> --code '<colorStop offset={0.5} color="#FF0055" />'
node patch
dapi node patch ([path.json] | --json <str>)
Assigns JSX props on existing entities. The payload is an array of { id, …props }, taking exactly the props a JSX element takes (see the element reference). A failing entry applies none of its props and aborts the command. Renaming is patching name; recoloring is patching fill; paints and color stops are patchable too. A transition is patched as a transition prop on the outgoing clip (null removes it).
dapi node patch --json '[{ "id": 42, "x": 100, "opacity": 0.5 }]'
Note: src resolves asynchronously after the other props; patch it on its own to keep failure reporting unambiguous.
Inspecting the scene graph
node tree
dapi node tree [id] [--depth N]
An entity's subtree as nested JSON: structure only, with a compact description per node. The way to discover ids. Default depth 3; 0 means the full subtree. Omit the id for one tree per top-level node.
node ls
dapi node ls [ids...]
The raw entity records: every component the entity carries, in engine units. The property-level counterpart to tree. With no ids, lists the top-level nodes.
node grep
dapi node grep <pattern> [id] [-i] [-t <types...>] [-k <components...>] [-l] [-c]
Searches entity records by regex and prints matching entities with the components that matched. [id] scopes to a subtree. -t filters by node type, -k restricts to specific components, -l prints refs only, -c prints a count. Find nodes by name with dapi node grep -k Name Title; find every entity with a Trim component with dapi node grep -k Trim ..
node capture
dapi node capture [id] [-t, --time <time...>] [--no-timestamp]
Focuses the node (or the active scene, if omitted) and captures it to a PNG at each given timeline position, each stamped in the top-left with its HH:MM:SS:FF timestamp (disable with --no-timestamp). Prints one { time, path } JSON line per capture.
selection
dapi selection ls # the selected nodes
dapi selection set [ids...] # replace the selection (no ids = clear)
dapi selection focus # pan/zoom the canvas to the selection
Mutations print the resulting selection, so calls can be chained without a follow-up read.
Editing nodes
node cp
Deep-clones nodes including descendants: dapi node cp <ids...>. Prints { sourceId, newId } per input.
node rm
Deletes nodes and their descendants: dapi node rm <ids...>.
Rendering
node render
dapi node render [id] [-o, --output <path>] ([config.json] | --json <str>)
Renders a scene to a video file, locally. Defaults to the active scene and an MP4 (H.264, 10 Mbps, 1080p, AAC 128 kbps) in the temp directory; prints { path }. Long-running: progress goes to stderr, stdout stays clean JSON. The encode window follows the scene's workarea.
All config fields are optional:
{
"format": "mp4", // "mp4" | "webm" | "ogg" | "mov"
"video": {
"codec": "avc", // "avc" | "hevc" | "vp9" | "av1" | "vp8"
"bitrate": 10000000, // bits/sec
"fps": 30, // default: the scene's frame rate
"resolution": 1080, // target height; width follows the scene's aspect
"enabled": true
},
"audio": {
"codec": "aac", // "aac" | "opus"
"bitrate": 128000,
"sampleRate": 48000,
"numberOfChannels": 2,
"enabled": true // false = video only
},
"trim": { "end": 30 } // seconds; cap the encode
}
Projects
dapi project active # the open project, or null
dapi project ls # all projects, most recent first
dapi project create [name] # create and open
dapi project set <id> # switch to a project
dapi project rm <id> # delete
Assets and folders
The library commands (asset add/ls/mv/rm/export, folder ls/create/rename/mv/rm) and the media-inspection commands (probe, transcribe, listen, filmstrip, waveform, frame) are covered in Working with media.
Discovery
models
dapi models [image|video|audio]
Lists the generation models available per media type, with each model's id and its constraints (durations, aspect ratios, features). These are what you reference from generate.* declarations.
voices
Lists the speech voices for generate.voice declarations.
fonts
dapi fonts [-f <pattern>] [-w <weights...>] [-s normal|italic] [-l <n>] [-n]
Lists local font families and variants (macOS only). -n prints plain family names. Works without the app running.