Skip to content

CLI reference

View Markdown
For agents

Give your agent this page’s Markdown link, or choose a collection.

Run dawn <command> --help for the exact options in the installed release. DAWN runs on macOS and Linux with Bun 1.3.14 or newer. Installation requires private repository access.

dawn collection init <new-dir> --id <slug> --title <text> --curator <name> [--template pack|artist|community] [--ci] [--json] creates an empty catalog and contribution guide in a new directory; --ci adds a pull request check workflow.

dawn collection add <catalog.json> <manifest-or-folder> [--id <slug>] [--kind <kind>] [--title <text>] [--credit <name>]... [--license <key>=<label>]... [--root <dir>] [--apply] [--json] proposes an entry for a palette, pack, loop, song or album, with every file’s digest and size; --apply adds it to the catalog.

dawn collection check <catalog.json> [--root <dir>] [--json] validates catalog metadata and local references without fetching remote content or evaluating project source.

dawn collection build <catalog.json> --out <new-dir> [--root <dir>] [--site] [--url <catalog-url>] [--no-traces] [--json] writes a deterministic portable catalog, its files, an integrity inventory, metadata-only trace exports and, with --site, a static page.

dawn collection install [<catalog-url-path-or-name> [entry...]] [--as <name>] [--ref <ref>] [--path <catalog-path>] [--root <dir>] [--project <dir>] [--offline] [--auth gh] [--max-bytes <n>] [--timeout <seconds>] [--json] pins the catalog’s commit, fetches and verifies the selected entries’ files into collections/ and records them in collections.lock.json. Without arguments it restores every locked entry from the cache.

dawn collection update [name [entry...]] [--dry-run] [--project <dir>] [--auth gh] [--json] prints or applies a reviewable update plan; edited files and locked songs are never replaced silently.

dawn collection remove <name> [entry...] [--delete-files] [--project <dir>] [--json] removes entries or a whole collection from the lock, keeping files unless asked.

dawn collection search [words...] [--kind <kind>] [--project <dir>] [--json] searches the collections the project added, offline.

dawn collection qualify [name [entry...]] [--timeout-ms <n>] [--max-seconds <n>] [--project <dir>] [--json] evaluates installed songs in the sealed song engine and checks the files they name and their render cost.

See Organize a collection.

A new project records a trace: dawn check, render, loop, section, form, sample, comments, migrate, mixqa and live append events to trace/ with prompts, source changes and results. trace/ is committed, so a git push publishes that text. dawn trace disable stops capture, dawn trace enable --no-text keeps metadata only, and DAWN_TRACE_CAPTURE=0 turns it off for one run. dawn trace note --kind <kind> --text "<words>" records a request, decision or handoff.

dawn trace start|append|read|check|export <project> records explicit local history. Event envelopes stay readable; larger JSON bodies are compressed and deduplicated. Export previews by default, and --apply creates a metadata-only copy in a new directory. See the project trace reference for what is recorded, input formats, limits and recovery.

dawn palette check <manifest.json> [--json] validates a local declarative palette. dawn palette export <manifest.json> <sound-id> <out.patch.json> [--json] exports one reusable patch to a new file. See Build a sound palette for the author workflow.

dawn palette pack <manifest.json> <out-dir> [--json] exports every sound with a compatible patch-pack manifest and checksums.

Command Inputs and result
dawn init [dir] Create the song, project marker, TypeScript configuration and vendored SDK. Existing authored files are kept.
dawn check Sync, typecheck and evaluate the project. Diagnostics identify source locations.
dawn lint Check key, harmony, register, prosody and repetition in a project or score; --json returns a report.
dawn render <out> Render a project, or a loop file selected with --import. The extension chooses the output format.
dawn link [project] Print the project’s score as a link. What does not travel in it is said on stderr; --json returns the link and the notices.
dawn open <link|file> [dir] Write a link as a new project folder of printed source. A folder that has files is never written into.
dawn comments List the project’s comments and where each lands in the song now; add, reply, edit, resolve, reopen, delete.

dawn render writes WAV and Standard MIDI Files locally. .m4a and .opus exports require FFmpeg. .score.json writes the versioned score format, which a web player can draw without the audio engine.

Render option Meaning
--section <name> Export one named song section
--normalize <target> Apply a loudness target to this export, such as streaming
--measure Print loudness and peak measurements for audio output
--rate <hz> Set the audio sample rate, such as 48000
--stems <dir> Export individual track stems
--stem-format <wav|flac> Write stems as float WAV (default) or 24-bit FLAC
--jobs <n> Bound parallel rendering work
--cache Reuse eligible rendered work
--title <text>, --artist <text> Set score JSON metadata

Audio options do not apply to .score.json. An ordinary offline render opens no audio device and sends no song data to a server.

--stems writes one file per track and premaster (the mix before the master chain) as the song renders, so a long song’s stems are never held in memory at once; a stem render needs about as much memory as the plain render. Float WAV stems are 32-bit, about 0.4 MB a second each. --stem-format flac writes each as 24-bit FLAC instead, encoded beside the render on other cores: the float rounded to the nearest 2^-23, a seventh to a thirtieth of the size. A sample at or past full scale is held there and reported (the pre-master mix is clamped there too).

dawn link writes the score into the link itself, after the #: nothing is uploaded and no account is needed. The link carries the song as DAWN prints it, so the command says first what stays behind:

  • your own code, in the files that differ from the printed form (helpers, loops and constants become plain notes);
  • signals such as sine and perlin, which travel as the automation points they were baked to;
  • audio files, which are listed with their size and whether each is a pack sound or a file to send;
  • that a link over 4,000 characters is long enough for some apps to cut, with a file as the way to send it whole.

A link holds 32,768 characters. A longer song gets no link and a line that says how long it would have been.

A project’s comments travel in its link, with the names their writers chose, and the command says how many. dawn link --no-comments leaves them out. A link holds 1,024 comments; past that, whole threads are left out, resolved ones first and then the oldest, and the command says how many. When the song fits and its comments do not, no link is made and the line names --no-comments. dawn open writes the comments back as comments.jsonl.

dawn open accepts a link, the part of one from #d1. on, or a file with a link somewhere in its text. It checks the link, writes a new folder (named dawn-link-<8 hex> unless you name one), evaluates what it wrote and compares that with the score in the link. A link that was cut or changed is refused with the reason, and nothing is written. A link made by an older DAWN is upgraded as it opens; one from a newer DAWN says to update.

Opened in a browser, a link lands on dawnav.com/open. That page reads the link in the browser, shows the tempo, key, length and track names, shows the link’s comments read-only (who, when, open or resolved, and where each points), and gives the dawn open command to copy. It says when a link was made at an older score version and upgraded to be read. It does not play the song, and the part of an address after the # is never sent, so nothing is uploaded.

A project’s comments are in comments.jsonl, one event a line, appended and never rewritten, so two people’s comments merge. Every command takes --dir <project> and --json.

Command Result
dawn comments [list] [--all] Open and resolved comments as threads, each with where it lands now. --all adds deleted ones.
dawn comments add "<text>" A new comment. With no place it is about the song.
dawn comments reply <id> "<text>" An answer in that comment’s thread. Threads are one level deep.
dawn comments edit <id> "<text>" New text for your own comment.
dawn comments resolve|reopen <id> Anyone may.
dawn comments delete <id> Your own comment only. Its text is no longer shown; its replies stay.
dawn comments score The revision and every note’s start tick, length in ticks and pitch, for a tool that anchors.

add takes a place: --track <id>, --section <name>, --bars <first>,<past last> (bars from 0), --ticks <first>,<past last>, and --note <tick>,<length>,<pitch> once for each note (with --track; up to 240). A comment has one track or none. The place is checked against the song as it is now and recorded with the song’s revision. An <id> may be shortened to any beginning that names one comment. The writer is your handle from dawn whoami, or nobody; --agent <name> or --person records who acted.

Each comment in a list has a state, exact, moved or lost. exact is the place the comment was written on. moved is shown and not known to be the place: its section is at other bars, some of its notes are gone, or the song changed and bars are all there is to go on. lost means its track, section or notes are gone; the comment is still listed, “on an earlier version”, with the bars and names it had, and can still be answered and resolved.

With --json the list is dawn.comments-cli/v1: revision, counts, song (ticksPerBeat, beatsPerBar, bars, ticks, seconds) and comments, each with id, text, author, at, state (open, resolved, deleted), anchor as written, own, replies, and now: the place state, ticks and seconds (a first and a past-last), bars, plays (where that range sounds in the song as its form plays it), the track with its current name, words, and was when it is not exact. A change returns the comment it changed. A refusal is {"ok": false, "code", "reason", "hint"} with exit 1 (exit 2 for command usage), and the same reason and hint on stderr without --json.

Command Result
dawn measure <mix.wav> --json Loudness, true peak, density and optional corridor checks
dawn mixqa [project] --json Mix checks from a render with stem taps
dawn mixqa --fix Write proposed mix moves into mix.patch.json
dawn eval [album-dir] Gate an album, songs or the fixture suite; --baseline compares a report
dawn judge <mix.wav> Run an optional learned judge after configuring its backend

With no --kind, dawn mixqa chooses the loudness corridor nearest the master target. A target outside that corridor shifts the loudness range and adjusts peak-to-loudness ranges for that target; balance, stereo and hygiene ranges stay fixed. Name --kind banger or --kind ballad to use that corridor unchanged. JSON reports include target with the target LUFS and the range shift when the target selected the corridor.

These reports describe their measured inputs. Listen to a render before accepting a musical edit, and keep prior source and reports when comparing changes.

dawn loop --section <name> adds a part to a song. When its name and prompt specify no part, additions alternate a quieter verse and a full chorus. Name a part such as Verse or Bridge, or include a part word such as drop in the prompt, to choose it. One-part and no-drums requests keep their own shape.

dawn make, dawn song, dawn album, dawn workflow, dawn vocals, dawn reference and dawn media cover drafting, durable jobs, singing and audio preparation. The workflow guide describes their prerequisites and effects.

dawn song --palette <palette.json|collection/entry> voices the composed song with a palette’s sounds: each part takes the sound with its role at the level of the sound it replaces. The command prints which sound plays each part, and style.resolved.json records it under voicing. Without --palette the song is unchanged. See Voice a song with a palette.

dawn song [dir] --composer <folder|collection/entry> composes with a composer plug-in instead of DAWN’s own composer: someone else’s code, run in the sealed song engine with no file, network or clock access, whose song DAWN checks like any song.ts and writes as an ordinary project. --composer dawn is the built-in. See Write a composer plug-in.

Command Result
dawn --version Installed DAWN version
dawn update --check Inspect a newer release; exit three means an update is waiting
dawn update Verify and install the latest accessible immutable release
dawn update --rollback Return to the previous installed version
dawn changes --since <version> Describe SDK changes and replacements
dawn migrate Preview project-format changes without applying them
dawn migrate --list Every source step and score-version step this DAWN knows
dawn migrate --apply Apply the migration and retain its recovery backup
dawn migrate --undo Restore the latest migration backup
dawn migrate --only <id> Preview, or with --apply run, one step by name, held or not

A project records the score version its source is written for in dawn.json ("score"). dawn check ends with it (score version 1), and when a newer DAWN has moved on it says score version 1 of 2 with one line for each step: what changed and what dawn migrate does about it. Such a project still checks and renders. dawn migrate --apply upgrades it: the song is printed again from the upgraded score, so code of your own in song.ts and the track files becomes plain notes, and dawn migrate --undo puts everything back. The score is at version 1 and has no steps yet.

The updater needs GitHub access and network connectivity. DAWN_NO_UPDATE_CHECK=1 disables background update checks. Use it in repeatable automation.

dawn login, dawn whoami, dawn logout and dawn publish <album-slug> are the configured publishing-server interface. Publication renders and uploads a song, so review its source and assets first. Server accounts and publication are separate from offline composition.

The publishing guide covers device sign-in, track destinations, visibility and token management.

From a terminal, dawn sends anonymous usage counts: the command’s name, whether it worked and how long it took, never arguments, paths or files. Outside Europe this is on by default and the first run prints a notice on stderr; in Europe the notice asks and nothing is sent until dawn telemetry on. CI runs and runs whose output is piped (agents, scripts, the Mac app’s own processes) send nothing and print nothing unless DAWN_TELEMETRY=1 is set.

Command Effect
dawn telemetry Whether counts are sent, why, and the file that keeps it
dawn telemetry off Stop sending and forget this install’s ID
dawn telemetry on Send counts

DO_NOT_TRACK=1 or DAWN_TELEMETRY_DISABLED=1 also turn it off without writing anything. The privacy policy says what is kept.

Documentation drafted with AI and checked against the product source.