README.md

dapi CLI Reference

Reference for dapi, the Diffusion Studio CLI. Every canvas and project command talks to the running app over a local socket. Responses are JSON written to stdout; errors are human-readable messages on stderr with a non-zero exit.

Each feature command has its own file (linked below). The JSX code syntax consumed by mount and node insert is specified in jsx/; the markup is pseudo-SVG, mirroring SVG's shape-and-paint model with the editor's own tags and props rather than the SVG spec.

Groups

Top-level: open, whoami, logs, screenshot, report, context (alias ctx), mount, models, voices, fonts, fetch.

Group	Alias	Scope
selection	sel	Read and mutate the current node selection.
node	n, entity	Anything that targets one or more nodes; scenes are nodes too.
project	p	Create, list, open, and delete projects.
asset	a	Manage and inspect assets in the open project.
folder	fld	Organize the asset library into folders.

How the surface is divided:

• Declarative composition happens through mount, which renders a Solid JSX project into the canvas (see jsx/); node insert runs the same pipeline but inserts the rendered nodes into an existing parent entity instead of mounting document roots.
• Scenes are created declaratively via mount (the scene property on a root, e.g. <rect scene="...">); there is no imperative scene command.
• AI asset generation (image / video / speech / audio) is declared in the project module (generate.*, see jsx/generate.md) and produced on mount. models and voices list what those declarations can reference.
• Inspecting an existing asset (probe / transcribe / listen / filmstrip / waveform / grab) lives under media; writing an asset's original file back to disk is asset export.
• Organizing the library lives under folder; moving assets between folders is asset mv.

Commands

App

• dapi open: launch the app, or open a file, folder, or deep link
• dapi whoami: print the authenticated account
• dapi logs: recent console output from the running app
• dapi screenshot: capture the entire application window as a PNG
• dapi report: file a GitHub issue about a bug in the CLI or the app, with diagnostics attached

Document

• dapi context: essential context about the open project
• dapi mount: compile a Solid JSX project module and mount it into the canvas

Selection

• dapi selection ls: list the selected nodes
• dapi selection set: replace the selection
• dapi selection focus: frame the selection on the canvas

Nodes

• dapi node ls: raw entity records
• dapi node tree: an entity's subtree as nested JSON
• dapi node grep: search entity records with a regex
• dapi node capture: capture a node to a labelled contact sheet, or one PNG per position
• dapi node insert: insert JSX tags into an existing parent
• dapi node rm: delete entities
• dapi node cp: deep-clone nodes
• dapi node patch: assign JSX props on existing entities
• dapi node render: render a scene to a video file

Projects

• dapi project active: print the active project
• dapi project ls: list projects
• dapi project create: create and open a project
• dapi project set: set the active project
• dapi project rm: delete a project

Assets

• dapi asset add: add local files as assets
• dapi asset ls: raw asset records
• dapi asset tree: the library as its folder tree
• dapi asset rm: delete assets
• dapi asset mv: move assets into a folder
• dapi asset export: write assets' original bytes to disk

Media

• dapi media probe: container and track metadata
• dapi media transcribe: timed speech transcript
• dapi media grab: decode video frames to a labelled contact sheet, or one PNG per frame
• dapi media filmstrip: grid of video frames as a PNG
• dapi media waveform: audio waveform PNG with silence highlighting
• dapi media listen: AI description of an audio track

Folders

• dapi folder ls: list child folders
• dapi folder create: create a folder
• dapi folder rename: rename a folder
• dapi folder mv: reparent folders
• dapi folder rm: delete folders (cascades)

Generation reference

• dapi models: list generation models and constraints
• dapi voices: list speech voices

Fonts

• dapi fonts: list local fonts

Download

• dapi fetch: download a video with yt-dlp (installed separately)

Shared types

NodeRef = { id: number; name: string; type: string }    // node ids are entity ids: integers
Size    = { width: number; height: number }
Asset   = { id: string; name: string; type: string }    // asset ids are opaque strings (sqids)
Folder  = { id: string; name: string; type: 'folder' }  // folder ids are opaque strings (sqids)
Time    = number | `${number}f` | "MM:SS"               // seconds, frames at 30 fps ("45f"), or a clock string; see jsx/timing.md

Time inputs take the Time format unless noted otherwise. Times in outputs are plain seconds, except the raw records of node ls, which use engine units (frames at 30 fps, packed colors, dB).

Conventions

• Stdout is JSON. Commands that return a single record emit one JSON value. Commands that return a collection emit JSON Lines (one object per line, no surrounding array) so per-item results stay streamable. node tree and asset tree emit one nested object per root. Exceptions: open for file / URL / no-target writes nothing; fonts --names-only writes plain family names; logs writes plain formatted log lines; mount and node insert write nothing.
• Batch commands are fail-fast (node rm, node patch, asset add, …): one invalid input fails the whole command with a single stderr message and exit 1. Ids are validated before anything changes, so a failed rm/mv/cp changes nothing; there are no per-item partial results.
• Unix-style names are canonical: list/read is ls, delete is rm, duplicate is cp, move/reparent is mv, search is grep. The longer English forms (list, remove, duplicate, move) are aliases of the Unix forms, not the other way around. get is a universal alias for ls. Commands without a natural Unix equivalent (tree, rename, patch, add, create, active, context, whoami, open, focus, set) keep their descriptive names.
• Stderr: human-readable error messages.
• Exit codes: 0 on success, 1 on any error (missing file, app not running, invalid input, IPC error).
• App must be running: every command except open, fonts, and fetch talks to the open Diffusion Studio instance. If the app isn't running, the CLI prints an instruction to launch it and exits 1. report is the one command that reads from the app but tolerates its absence, recording it in the issue instead of failing.