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 |
npm run marrow <args>
# or directly
node packages/cli/dist/index.js <args>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
marrow validate <file...> [--json] [--no-icons] [--packs <dir>]
marrow build <file> [-o <out>] [--single] [--static-svg] [--embed] [--chrome minimal|full] [--packs <dir>] [--config <file.yaml>]
marrow serve <file-or-dir> [--port <n>] [--host <addr>] [--packs <dir>] [--config <file.yaml>]
marrow import <v1-file> [-o <out.yaml>] [--packs <dir>]
marrow snapshot <file> [-o <out.png>] [--focus <device-id>] [--theme <dark|light>] [--json] [--packs <dir>] [--config <file.yaml>]
marrow icons search <query...> [--json] [--max <n>] [--packs <dir>]
marrow icons packs [--packs <dir>]
marrow icons fetch [pack...] [--yes] [--packs <dir>]
marrow schema
marrow helpExit 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.
npm run marrow -- validate input/branch.yaml
npm run marrow -- validate input/*.yaml
npm run marrow -- validate input/branch.yaml --json| 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.
npm run marrow -- build input/branch.yaml
npm run marrow -- build input/branch.yaml -o dist/net.html
npm run marrow -- build input/big.yaml --single
npm run marrow -- build input/branch.yaml --embed
npm run marrow -- build input/branch.yaml --static-svg -o dist/net.svg| Flag | Effect |
|---|---|
-o <out> | Output path. Defaults to output/<name>.html (or output/<name>.svg with --static-svg) |
--single | Force one file even above the split threshold |
--static-svg | Export static standalone vector SVG instead of interactive HTML |
--embed | Pre-configure minimal chrome mode (#embed=true) for iframe embedding |
--chrome <minimal|full> | Specify default UI chrome mode (minimal hides topbar, search dock, and sidebar) |
--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.
npm run marrow -- serve input
npm run marrow -- serve input/branch.yaml
npm run marrow -- serve input --host 0.0.0.0 --port 5300| 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.
npm run marrow -- snapshot input/branch.yaml -o /tmp/branch.png
npm run marrow -- snapshot input/branch.yaml -o /tmp/x.png --focus core-sw-01
npm run marrow -- snapshot input/branch.yaml -o /tmp/x.png --theme light| 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.
npm run marrow -- import legacy/hq.yaml -o input/hq.yaml
npm run marrow -- import legacy/hq.yaml # to stdoutAlways validate the result. See Importing legacy YAML.
icons
npm run marrow -- icons search firewall
npm run marrow -- icons search "layer 3 switch" --max 40 --json
npm run marrow -- icons packs
npm run marrow -- icons fetch # aws + azure + gcp, with a prompt
npm run marrow -- icons fetch aws --yes # one pack, non-interactive| 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
npm run marrow -- schema > schema.jsonEmits the JSON Schema for the topology format. The published copy is at
/schema.json.
help
npm run marrow -- help
npm run marrow -- --help