CLI
Every marrow command and flag, with exit codes.
Run from the repository root. The commands you reach for daily have npm shortcuts:
| Shortcut | Runs |
|---|---|
npm run dev | marrow serve input — live preview, hot reload |
npm run dev:lan | the same, bound to 0.0.0.0 for the LAN |
npm run build <file> | marrow build <file> |
npm run validate <file...> | marrow validate <file...> |
npm run snapshot <file> | marrow snapshot <file> |
npm run icons <args> | marrow icons <args> |
npm run marrow <args> | anything else — import, schema |
Flags need a -- separator. npm strips flag names from npm run arguments
and forwards only their values, so npm run build net.yaml -o out.html silently
passes out.html as a second positional. Write npm run build -- net.yaml -o out.html. Bare file paths are fine without it.
If dist/ is stale — right after git pull — run npm run compile. A fresh
clone compiles itself: npm install runs it for you. Odd behavior from
validate or build is almost always a stale build.
Synopsis
Exit codes
| Code | Meaning |
|---|---|
0 | Valid / succeeded |
1 | Validation errors |
2 | Usage or I/O error |
The split matters in CI: 1 means "your topology is wrong", 2 means "you
called me wrong or a file is missing". Unknown flags are a usage error, not a
stack trace.
validate
Schema and reference check. Run it before you claim anything is ready.
| Flag | Effect |
|---|---|
--json | Machine-readable diagnostic report |
--no-icons | Skip icon-existence checking — faster, and useful when packs aren't installed |
--packs <dir> | Use an icon-packs directory other than ./icon-packs |
Accepts multiple files. Exits 1 if any file has errors; warnings alone still
exit 0.
build
Compile to HTML.
| Flag | Effect |
|---|---|
-o <out> | Output path. Defaults to output/<name>.html |
--single | Force one file even above the split threshold |
--packs <dir> | Alternative icon-packs directory |
--config <file> | Alternative marrow.config.yaml |
Above 150 devices or 5 zones with devices, output is a directory rather than a file — see Output shapes.
serve
Live preview: watch, rebuild, live-reload. Serves exactly what build ships.
| Flag | Default | Effect |
|---|---|---|
--port <n> | 5200 | Listen port |
--host <addr> | 127.0.0.1 | Bind address. 0.0.0.0 exposes it on the LAN |
--packs <dir> | Alternative icon-packs directory | |
--config <file> | Alternative config |
There is no authentication. Only run one server per port.
snapshot
Render to a PNG. This is how an agent sees its own work.
| Flag | Effect |
|---|---|
-o <out.png> | Output image path |
--focus <device-id> | Center the camera on one device |
--theme <dark|light> | Override the topology's theme |
--json | Emit metadata about the render |
--packs <dir> | Alternative icon-packs directory |
--config <file> | Alternative config |
Uses Playwright. The first run may need npx playwright install chromium.
import
Convert legacy v1 YAML (or discovery-crawler output) to v2.
Always validate the result. See Importing legacy YAML.
icons
| Subcommand | Purpose |
|---|---|
search <query...> | Find real icon ids. --max <n> defaults to 20 |
packs | Show the packs root and how many icons loaded |
fetch [pack...] | Install aws/azure/gcp from the vendors. --yes skips consent |
schema
Emits the JSON Schema for the topology format. The published copy is at
/schema.json.