# CLI reference

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](/docs/first-song#install-dawn) requires private repository access.

## Collections

`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](/docs/collections).

## Project traces

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](/docs/traces) for what is recorded, input formats, limits and recovery.

## Sound palettes

`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](/docs/palettes) for the author workflow.

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

## Projects and exports

| 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](/docs/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).

### A project as a link

`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.

### Comments

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`.

## Measure and improve a mix

| 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.

## Compose and work with media

`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](/docs/workflows) 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](/docs/palettes#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](/docs/composers).

## Versions and recovery

| 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.

## Optional publication

`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](/docs/publishing) covers device sign-in, track destinations, visibility and token management.

## Usage counts

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](https://dawnav.com/privacy#cli) says what is kept.
