editor/reference
konstantin-paulus 8eafe46f16 Update capture functionality and documentation for node IDs
- Changed the `id` type in `CaptureRequest` from number to string to accommodate JSX element IDs.
- Refactored the `resolveNode` function to handle string IDs, improving error handling for ambiguous and non-existent nodes.
- Updated the `README.md` and `capture.md` to clarify the expected format for node IDs, including the use of `file:id` for disambiguation.
- Enhanced the `dapi capture` command documentation to reflect changes in ID handling and provide clearer usage instructions.
2026-08-24 10:58:54 +02:00
..

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 specified in jsx/ 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: whoami, logs, screenshot, report, context (alias ctx), capture, models, voices, fonts, fetch.

Group Alias Scope
media m Inspect a media file by asset id or local path, without adding it to the project.

How the surface is divided:

  • AI asset generation (image / video / speech / audio) is declared in the project module (generate.*, see jsx/generate.md). models and voices list what those declarations can reference.
  • Inspecting an existing asset (probe / transcribe / listen / filmstrip / waveform / grab) lives under media.

Commands

App

  • 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 open: launch the app and open (or create) a project folder, anywhere on disk
  • dapi context: which project the app has open, where its playhead sits, and its registered fonts
  • dapi capture: render a node in isolation to a labelled contact sheet, or one PNG per position

Media

Generation reference

Fonts

Download

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

Shared types

Asset = { id: string; path: string; type: string }  // asset ids are content hashes; `path` is the library path
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.

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. Exceptions: fonts --names-only writes plain family names; logs writes plain formatted log lines.
  • Unix-style names are canonical. Commands without a natural Unix equivalent (context, whoami) 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 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.