Skip to content

README.md

Latest commit

 

History

History
76 lines (50 loc) · 4.95 KB

README.md

File metadata and controls

76 lines (50 loc) · 4.95 KB
Raw

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.

A project is a folder of that JSX, and the source is the document: the app compiles the entry file and renders every element into an editable node, and edits made on the canvas are written back to the element that authored them. So the loop is dapi open <dir> once, then edit the files — there is no command that pushes content into the app. What the commands do is read the running app (context, capture, logs), inspect media, and list what a declaration may name.

Groups

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

Group Alias Scope
media m Inspect a media file by path, without adding it to the project. Local files and URLs work with or without an open project; library paths need one.

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, its registered fonts, and where its generations stand
  • dapi capture: render frames of a scene, as an export would, to a labelled contact sheet or one PNG per position
  • dapi check: check a node's subtree for structural mistakes (black-frame gaps, never-visible nodes, failed sources) and report subtree stats

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
NodeId = string                                     // an element's `id` in the project's JSX; `file:id` when two files collide

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.