# CLI reference Every `arch` command, flag, format and exit code — generated from the same capability manifest that `arch manifest --json` serves, so this page cannot fall behind the CLI. The CLI is ArchLang's **primary agent interface**. Every command takes `--json` (structured result on **stdout**, human messages on **stderr**), and every command that reads source accepts a file path or `-` for stdin. ```bash npx @chanmeng666/archlang help # zero-install arch manifest --json # this page, as data ``` ## Exit codes | Code | Meaning | | --- | --- | | `0` | ok | | `1` | internal / IO error | | `2` | user-source error (deterministic — fix it, don't blindly retry) | | `3` | bad usage | ## Output formats `-f ` on `compile`, `batch`, `md` and `preview`. | Format | Dependency | | --- | --- | | `svg` | zero-dep (built in) | | `dxf` | zero-dep (built in) | | `txt` | zero-dep (built in) | | `pdf` | needs optional `pdfkit` | | `png` | needs optional `@resvg/resvg-js` | ## Global flags | Flag | Does | | --- | --- | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | ## Commands ### `arch compile` render a plan to SVG/DXF/TXT/PDF/PNG **Input:** ` (Plan JSON with --from-json)` · **Output:** file (or stdout with -o -) — with --json and no -o nothing is written | Flag | Does | | --- | --- | | `--out, -o ` | output file, or '-' for stdout (default: the input path with the format's extension) | | `--format, -f ` | output format (default svg) | | `--level ` | render only this storey of a multi-storey plan (level blocks) to the plain -o target, instead of one <stem>.L<level>.<ext> file per level | | `--width, -w ` | page width hint in pixels | | `--scale, -s ` | raster scale for the PNG backend (ignored by the non-raster formats) | | `--cols ` | text renderer (-f txt / preview --ascii) grid width in characters (default 80) | | `--charset ` | text renderer glyph set (default unicode) | | `--overlay ` | draw an opt-in diagnostic overlay (circulation walks + bottleneck markers); default output is unchanged | | `--error-svg` | on a broken plan, still emit a self-describing error-card image listing the diagnostics (exit code stays 2); it is an output like any other, so with --json and no -o nothing is written and the card is not in the payload — pass -o <file> to get the image | | `--accessible` | emit <title>/<desc>/role/aria accessibility metadata (the describe() caption) into the SVG; default output is unchanged | | `--acc-id-prefix ` | with --accessible, prefix the <title>/<desc> element ids (default arch, giving arch-title/arch-desc) so several plans inlined in one HTML page do not share them; ignored without --accessible | | `--from-json` | read the input as Plan JSON (RPLAN shape) instead of .arch, convert it, then compile | | `--install` | auto-install the optional dep for the chosen format if missing (PNG/PDF) | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | | `--view ` | render an illustrative axonometric of the building instead of the plan (iso = true isometric, axon = the 30/60 plan oblique) — a picture, never a measured drawing: no scale, no title block, no dimensions, and `describe`/`lint` are unaffected | **Examples** ```bash # render to the named file; structured result on stdout $ arch compile plan.arch -o plan.svg --json # check it compiles and WRITE NOTHING (no -o names a file) — reports written:false, bytes, diagnostics, summary $ arch compile plan.arch --json # render SVG next to the input (plan.svg) $ arch compile plan.arch # compile source from stdin straight to SVG on stdout $ arch compile - -o - < plan.arch # rasterize to PNG, fetching the optional renderer if it is missing $ arch compile plan.arch -f png -o plan.png --install --json # a multi-storey plan writes one sheet per level (house.L1.svg, house.L2.svg …) and reports outputs[] $ arch compile house.arch -o house.svg --json # render just the upper storey of a multi-storey plan to one file $ arch compile house.arch --level 2 -o upper.svg # an illustrative isometric of the whole building (every storey in ONE drawing, so no per-level fan-out) $ arch compile house.arch --view iso -o house-iso.svg ``` ### `arch batch` render many .arch files in one call, concurrently **Input:** ` …` · **Output:** one file per input; --json gives a results[] array | Flag | Does | | --- | --- | | `--out, -o ` | output DIRECTORY for every rendered file (default: alongside each input) | | `--format, -f ` | output format (default svg) | | `--jobs, -j ` | max concurrent renders (default: CPU count) | | `--width, -w ` | page width hint in pixels | | `--scale, -s ` | raster scale for the PNG backend (ignored by the non-raster formats) | | `--cols ` | text renderer (-f txt / preview --ascii) grid width in characters (default 80) | | `--charset ` | text renderer glyph set (default unicode) | | `--overlay ` | draw an opt-in diagnostic overlay (circulation walks + bottleneck markers); default output is unchanged | | `--error-svg` | on a broken plan, still emit a self-describing error-card image listing the diagnostics (exit code stays 2) | | `--accessible` | emit <title>/<desc>/role/aria accessibility metadata (the describe() caption) into the SVG; default output is unchanged | | `--acc-id-prefix ` | with --accessible, prefix the <title>/<desc> element ids (default arch, giving arch-title/arch-desc) so several plans inlined in one HTML page do not share them; ignored without --accessible | | `--install` | auto-install the optional dep for the chosen format if missing (PNG/PDF) | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # render design variants concurrently; one result row per input $ arch batch a.arch b.arch c.arch -o out/ --json # export a whole directory to DXF, 4 renders at a time $ arch batch plans/*.arch -f dxf -j 4 --json ``` ### `arch md` _(alias: `markdown`)_ render every ```arch block in a Markdown file and rewrite to image links **Input:** `` · **Output:** out.md + one image per block | Flag | Does | | --- | --- | | `--out, -o ` | rewritten Markdown file, or '-' for stdout (default: <name>.out.md) | | `--format, -f ` | image format for the blocks (default svg) | | `--width, -w ` | page width hint in pixels | | `--scale, -s ` | raster scale for the PNG backend (ignored by the non-raster formats) | | `--overlay ` | draw an opt-in diagnostic overlay (circulation walks + bottleneck markers); default output is unchanged | | `--error-svg` | on a broken plan, still emit a self-describing error-card image listing the diagnostics (exit code stays 2) | | `--accessible` | emit <title>/<desc>/role/aria accessibility metadata (the describe() caption) into the SVG; default output is unchanged | | `--acc-id-prefix ` | with --accessible, prefix the <title>/<desc> element ids (default arch, giving arch-title/arch-desc) so several plans inlined in one HTML page do not share them; ignored without --accessible | | `--install` | auto-install the optional dep for the chosen format if missing (PNG/PDF) | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # render the fenced arch blocks to SVGs and rewrite them to image links $ arch md README.md -o README.out.md --json # PNG images; a broken block still yields an error card $ arch md doc.md -f png --error-svg --json ``` ### `arch preview` render a PNG you can look at (zero-install where the optional binary is present) **Input:** `` · **Output:** PNG file (or ASCII text on stdout with --ascii) | Flag | Does | | --- | --- | | `--out, -o ` | output PNG file, or '-' for stdout (default: <name>.png) | | `--scale, -s ` | raster scale (default 1; without -w/-s the page auto-targets ~1600px wide for legibility) | | `--width, -w ` | page width hint in pixels | | `--ascii` | print a zero-dependency ASCII text plan to stdout instead of a PNG | | `--level ` | preview this storey of a multi-storey plan (default: the lowest level, i.e. page 1) | | `--cols ` | text renderer (-f txt / preview --ascii) grid width in characters (default 80) | | `--charset ` | text renderer glyph set (default unicode) | | `--overlay ` | draw an opt-in diagnostic overlay (circulation walks + bottleneck markers); default output is unchanged | | `--error-svg` | on a broken plan, still emit a self-describing error-card image listing the diagnostics (exit code stays 2) | | `--install` | auto-install @resvg/resvg-js if missing, then render | | `--view ` | render an illustrative axonometric of the building instead of the plan (iso = true isometric, axon = the 30/60 plan oblique) — a picture, never a measured drawing: no scale, no title block, no dimensions, and `describe`/`lint` are unaffected | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # a zero-dependency text plan an agent can read on stdout $ arch preview plan.arch --ascii --json # raster the plan so a vision model can look at it $ arch preview plan.arch -o plan.png --json # look at one storey of a multi-storey plan $ arch preview house.arch --level 2 -o upper.png --json # raster an illustrative plan-oblique of the building so a vision model can look at it $ arch preview house.arch --view axon -o house-axon.png --json ``` ### `arch watch` recompile on save (interactive) **Input:** `` · **Output:** file, rewritten on each save | Flag | Does | | --- | --- | | `--out, -o ` | output file, or '-' for stdout (default: the input path with the format's extension) | | `--format, -f ` | output format (default svg) | | `--level ` | render only this storey of a multi-storey plan (level blocks) to the plain -o target, instead of one <stem>.L<level>.<ext> file per level | | `--width, -w ` | page width hint in pixels | | `--scale, -s ` | raster scale for the PNG backend (ignored by the non-raster formats) | | `--cols ` | text renderer (-f txt / preview --ascii) grid width in characters (default 80) | | `--charset ` | text renderer glyph set (default unicode) | | `--overlay ` | draw an opt-in diagnostic overlay (circulation walks + bottleneck markers); default output is unchanged | | `--error-svg` | on a broken plan, still emit a self-describing error-card image listing the diagnostics (exit code stays 2); it is an output like any other, so with --json and no -o nothing is written and the card is not in the payload — pass -o <file> to get the image | | `--accessible` | emit <title>/<desc>/role/aria accessibility metadata (the describe() caption) into the SVG; default output is unchanged | | `--acc-id-prefix ` | with --accessible, prefix the <title>/<desc> element ids (default arch, giving arch-title/arch-desc) so several plans inlined in one HTML page do not share them; ignored without --accessible | | `--from-json` | read the input as Plan JSON (RPLAN shape) instead of .arch, convert it, then compile | | `--install` | auto-install the optional dep for the chosen format if missing (PNG/PDF) | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # recompile on every save (interactive; agents should use compile) $ arch watch plan.arch -o plan.svg ``` ### `arch validate` parse + resolve + lint, no render (is it valid & sound?) **Input:** `` · **Output:** diagnostics (plus a graph{} report with --graph and an intent{ ok, satisfied, total, subscores, violations } block with --intent) | Flag | Does | | --- | --- | | `--strict, --fail-on-warning` | advisory warnings fail too (exit 2) | | `--graph ` | also check the plan's interior-door adjacency against an intended graph (bare dict or {input_graph:{…}}); mismatch → exit 2 | | `--intent ` | gate the plan against a brief's intent JSON; a failing gating assertion (room count/existence/area/windows) → exit 2. Adjacency/reachability score but never gate. Composes with --graph. | | `--feedback` | with --intent, append a deterministic per-violation correction prompt (advisory data, never applied) | | `--code ` | show only diagnostics with these codes — a DISPLAY filter: the exit code and `ok` still come from the unfiltered set | | `--severity ` | show only diagnostics of this severity — a DISPLAY filter, like --code (never changes the exit code) | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # the ship gate: errors and advisory warnings both fail $ arch validate plan.arch --strict --json # gate on a brief's intent contract and get per-violation correction prompts $ arch validate plan.arch --intent brief.json --feedback --json # check interior-door adjacency against an intended room graph $ arch validate plan.arch --graph rooms.json --json # read only the blocking errors; `ok` and the exit code still weigh every diagnostic $ arch validate plan.arch --severity error --json ``` ### `arch describe` semantic facts: rooms, areas, adjacency, what doors connect **Input:** `` · **Output:** facts (JSON or a summary), narrowed by --room/--zone/--select/--level | Flag | Does | | --- | --- | | `--room ` | keep only these rooms; doors/windows/openings/furniture narrow to the ones touching them (plan-level facts — bbox, totals, caption — stay whole-plan) | | `--zone ` | keep only the rooms declared in these `zone` blocks (nested zones roll up; paths are dotted, e.g. west.galleries) — a DISPLAY filter: `ok` and the exit code still weigh the whole plan | | `--select ` | emit only these top-level keys of the --json object (rooms, doors, totals, access, circulation, freedom, …); the ok/plan/units/diagnostics envelope is always kept | | `--level ` | report this storey of a multi-storey plan as the top-level facts (a DISPLAY filter — `ok` and the exit code still weigh the whole plan) | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # rooms, areas, adjacency, door connections, caption, freedom — confirm the plan means what you intended $ arch describe plan.arch --json # describe source piped on stdin, no temp file $ arch describe - --json < plan.arch # just the rooms and the totals — keep a big plan's facts inside a bounded context $ arch describe plan.arch --select rooms,totals --json # only those two rooms and the doors/windows/furniture that touch them $ arch describe plan.arch --room kitchen,bath --json # only the west wing's rooms and what touches them; `zones[]` reports every declared wing, its rooms and its area $ arch describe museum.arch --zone west --json # the upper storey's rooms/areas/access as the top-level facts (`levels[]` carries every storey) $ arch describe house.arch --level 2 --json ``` ### `arch score` continuous intent satisfaction (satisfied/total) as data — the refine-loop reward. Measures, never gates (validate --intent is the gate). **Input:** `` · **Output:** { ok, satisfied, total, score, subscores, violations } (exit 0 on a successful measurement, even when assertions fail) | Flag | Does | | --- | --- | | `--brief ` | the intent JSON to measure satisfaction against (required) | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # continuous intent satisfaction as the refine-loop reward; always exits 0 on a measurement $ arch score plan.arch --brief brief.json --json ``` ### `arch lint` architectural soundness warnings **Input:** `` · **Output:** W_* warnings (narrowed by --code/--severity; `filtered`/`total_diagnostics` mark a filtered result) | Flag | Does | | --- | --- | | `--profile ` | advisory ruleset | | `--strict, --fail-on-warning` | warnings fail (exit 2) | | `--code ` | show only diagnostics with these codes — a DISPLAY filter: the exit code and `ok` still come from the unfiltered set | | `--severity ` | show only diagnostics of this severity — a DISPLAY filter, like --code (never changes the exit code) | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # architectural soundness warnings as data, each with a fix $ arch lint plan.arch --json # gate on the accessibility ruleset (any warning exits 2) $ arch lint plan.arch --profile accessibility-advisory --strict # read only the reachability warnings; the exit code still reflects every diagnostic $ arch lint plan.arch --code W_ROOM_UNREACHABLE,W_NO_ENTRANCE --json ``` ### `arch ast` parse only (no resolve/render) and print the span-bearing AST as JSON **Input:** `` · **Output:** AST JSON (scripting nodes unexpanded) | Flag | Does | | --- | --- | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # span-bearing parse tree with no resolve or render — locate a statement by byte offset $ arch ast plan.arch --json ``` ### `arch complete` completion items in scope at a source byte offset (the LSP completion() core) **Input:** `` · **Output:** { items: [...] } completion items | Flag | Does | | --- | --- | | `--at ` | source byte offset to list completions at (required) | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # what may legally be written at byte offset 120 $ arch complete plan.arch --at 120 --json # completions for source on stdin $ arch complete - --at 0 --json < plan.arch ``` ### `arch fmt` canonical formatting **Input:** `` · **Output:** formatted source (or in place with --write) | Flag | Does | | --- | --- | | `--write` | format the file in place | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # canonical source plus a `changed` flag, nothing written $ arch fmt plan.arch --json # rewrite the file in canonical form $ arch fmt plan.arch --write ``` ### `arch repair` explicit source-to-source corrector (furniture out of walls) + change log **Input:** `` · **Output:** corrected source + change log on stderr | Flag | Does | | --- | --- | | `--out, -o ` | output file for the corrected source, or '-' for stdout (default: stdout) | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # the geometric corrector: `source` + a `changes[]` log of every furniture move $ arch repair plan.arch --json # write the corrected source to a new file $ arch repair plan.arch -o repaired.arch ``` ### `arch fix` apply the machine-applicable fix suggestions on a plan's diagnostics (bounded fixpoint) **Input:** `` · **Output:** fixed source (to the input file or -o) + a unified diff and change log on stderr | Flag | Does | | --- | --- | | `--out, -o ` | output file for the fixed source, or '-' for stdout (default: rewrite the input file in place) | | `--unsafe` | also apply `maybe-incorrect` fixes (default: machine-applicable only) | | `--dry-run` | compute the result but do not write it (the diff preview still prints) | | `--backup` | before rewriting a file in place, save the original bytes to <file>.bak | | `--force` | keep a pass even if it raises the error count | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # preview the exact unified diff `fix` would write, changing nothing on disk $ arch fix plan.arch --dry-run # the same preview as data: which fixes would be applied, plus the `diff` they produce $ arch fix plan.arch --dry-run --json # apply the machine-applicable fixes in place, keeping the original as plan.arch.bak $ arch fix plan.arch --backup --json # also apply the maybe-incorrect fixes, leaving the input untouched $ arch fix plan.arch -o fixed.arch --unsafe --json ``` ### `arch suggest` advisory topology suggestions as data (door/window statements that resolve reachability/window faults) **Input:** `` · **Output:** suggestions (JSON or a summary) | Flag | Does | | --- | --- | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # ready-to-paste door/window statements for unreachable rooms, no entrance, or a windowless bedroom $ arch suggest plan.arch --json ``` ### `arch manifest` _(alias: `capabilities`)_ this document: the whole CLI API as structured data **Input:** `none` · **Output:** the manifest (JSON or a summary) | Flag | Does | | --- | --- | | `--json` | structured result on stdout, messages on stderr | **Examples** ```bash # discover every command, flag, format, and error code in one call $ arch manifest --json ``` ### `arch spec` print the one-prompt language spec (spec.llm.md) **Input:** `none` · **Output:** the spec | Flag | Does | | --- | --- | | `--json` | structured result on stdout, messages on stderr | **Examples** ```bash # the whole language on one page — read this before authoring $ arch spec ``` ### `arch context` print the full bundled agent context (spec + workflow + CLI + errors) **Input:** `none` · **Output:** the full agent context (llms-full.txt), or one --section of it | Flag | Does | | --- | --- | | `--section ` | print only one section of the bundle instead of all ~50KB of it (spec = the language, workflow = the agent loop, cli = every command, errors = the diagnostic catalog) | | `--json` | structured result on stdout, messages on stderr | **Examples** ```bash # the cold-start bundle: spec + workflow + CLI reference + every diagnostic $ arch context # just the diagnostic catalog — read one section instead of paying for the whole ~50KB bundle $ arch context --section errors ``` ### `arch new` _(alias: `init`)_ scaffold a starter .arch **Input:** `none` · **Output:** starter source | Flag | Does | | --- | --- | | `--out, -o ` | output file — refuses to overwrite an existing one without --force (default: stdout) | | `--force` | overwrite an existing file | | `--json` | structured result on stdout, messages on stderr | | `--quiet, -q` | suppress human messages on stderr | **Examples** ```bash # get the starter plan as a `template` string, writing nothing $ arch new --json # scaffold a starter file to edit $ arch new -o plan.arch ``` ### `arch explain` look up an error code (cause / fix / example) **Input:** `` · **Output:** catalog entry | Flag | Does | | --- | --- | | `--json` | structured result on stdout, messages on stderr | **Examples** ```bash # the catalog entry for a diagnostic code: cause, fix, example $ arch explain E_ROOM_SIZE --json ```