This page is generated from docs/cli-reference.md — edit it there.

CLI reference

Every archlang command, flag, format and exit code — generated from the same capability manifest that archlang 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.

npx -y @chanmeng666/archlang help        # zero-install
npm i -g @chanmeng666/archlang           # or install the archlang command
archlang manifest --json                 # this page, as data

arch is installed as an alias of archlang, but on Linux, macOS and Git Bash coreutils owns that name, so this page never uses it.

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 <format> on compile, batch, md and preview.

Format	Dependency
svg	zero-dep (built in)
dxf	zero-dep (built in)
txt	zero-dep (built in)
json	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

archlang compile

render a plan to SVG/DXF/TXT/PDF/PNG, or to Plan JSON

Input: <file.arch|-> (Plan JSON with --from-json) · Output: file (or stdout with -o -) — with --json and no -o nothing is written

Flag	Does
--out, -o <file|->	output file, or '-' for stdout (default: the input path with the format's extension)
--format, -f <svg|dxf|txt|json|pdf|png>	output format (default svg); json writes the Plan JSON that --from-json reads
--level <n>	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 <px>	page width hint in pixels
--scale, -s <n>	raster scale for the PNG backend (ignored by the non-raster formats)
--cols <n>	text renderer (-f txt / preview --ascii) grid width in characters (default 80)
--charset <unicode|ascii>	text renderer glyph set (default unicode)
--overlay <circulation>	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 <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 <iso|axon>	DEPRECATED (removed in 2.0; ArchLang draws plans) — 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

# render to the named file; structured result on stdout
$ archlang compile plan.arch -o plan.svg --json

# check it compiles and WRITE NOTHING (no -o names a file) — reports written:false, bytes, diagnostics, summary
$ archlang compile plan.arch --json

# render SVG next to the input (plan.svg)
$ archlang compile plan.arch

# compile source from stdin straight to SVG on stdout
$ archlang compile - -o - < plan.arch

# export the Plan JSON; `archlang compile plan.json --from-json` renders it back
$ archlang compile plan.arch -f json -o plan.json

# rasterize to PNG, fetching the optional renderer if it is missing
$ archlang 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[]
$ archlang compile house.arch -o house.svg --json

# render just the upper storey of a multi-storey plan to one file
$ archlang 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)
$ archlang compile house.arch --view iso -o house-iso.svg

archlang batch

render many .arch files in one call, concurrently

Input: <a.arch> <b.arch> … · Output: one file per input; --json gives a results[] array

Flag	Does
--out, -o <dir>	output DIRECTORY for every rendered file (default: alongside each input)
--format, -f <svg|dxf|txt|json|pdf|png>	output format (default svg); json writes the Plan JSON that --from-json reads
--jobs, -j <n>	max concurrent renders (default: CPU count)
--width, -w <px>	page width hint in pixels
--scale, -s <n>	raster scale for the PNG backend (ignored by the non-raster formats)
--cols <n>	text renderer (-f txt / preview --ascii) grid width in characters (default 80)
--charset <unicode|ascii>	text renderer glyph set (default unicode)
--overlay <circulation>	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 <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

# render design variants concurrently; one result row per input
$ archlang batch a.arch b.arch c.arch -o out/ --json

# export a whole directory to DXF, 4 renders at a time
$ archlang batch plans/*.arch -f dxf -j 4 --json

archlang md (alias: markdown)

render every ```arch block in a Markdown file and rewrite to image links

Input: <doc.md> · Output: out.md + one image per block

Flag	Does
--out, -o <out.md|->	rewritten Markdown file, or '-' for stdout (default: <name>.out.md)
--format, -f <svg|png>	image format for the blocks (default svg)
--width, -w <px>	page width hint in pixels
--scale, -s <n>	raster scale for the PNG backend (ignored by the non-raster formats)
--overlay <circulation>	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 <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

# render the fenced arch blocks to SVGs and rewrite them to image links
$ archlang md README.md -o README.out.md --json

# PNG images; a broken block still yields an error card
$ archlang md doc.md -f png --error-svg --json

archlang preview

render a PNG you can look at (zero-install where the optional binary is present)

Input: <file.arch|-> · Output: PNG file (or ASCII text on stdout with --ascii)

Flag	Does
--out, -o <out.png|->	output PNG file, or '-' for stdout (default: <name>.png)
--scale, -s <n>	raster scale (default 1; without -w/-s the page auto-targets ~1600px wide for legibility)
--width, -w <px>	page width hint in pixels
--ascii	print a zero-dependency ASCII text plan to stdout instead of a PNG
--level <n>	preview this storey of a multi-storey plan (default: the lowest level, i.e. page 1)
--cols <n>	text renderer (-f txt / preview --ascii) grid width in characters (default 80)
--charset <unicode|ascii>	text renderer glyph set (default unicode)
--overlay <circulation>	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 <iso|axon>	DEPRECATED (removed in 2.0; ArchLang draws plans) — 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

# a zero-dependency text plan an agent can read on stdout
$ archlang preview plan.arch --ascii --json

# raster the plan so a vision model can look at it
$ archlang preview plan.arch -o plan.png --json

# look at one storey of a multi-storey plan
$ archlang 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
$ archlang preview house.arch --view axon -o house-axon.png --json

archlang link

print a playground URL that opens the plan, rendered, with nothing to install

Input: <file.arch|-> · Output: the playground URL; --json gives { ok, playground, embed, bytes } (embed: the plan alone, for an iframe; bytes: the compressed plan). A plan that does not compile still gets a link: ok false with an errors count, one warning on stderr, exit 0

Flag	Does
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

Examples

# a URL to give the user: it opens the plan in the hosted playground
$ archlang link plan.arch

# the playground and embed URLs as data, and whether the plan compiles
$ archlang link plan.arch --json

archlang watch

recompile on save (interactive)

Input: <file.arch> · Output: file, rewritten on each save

Flag	Does
--out, -o <file|->	output file, or '-' for stdout (default: the input path with the format's extension)
--format, -f <svg|dxf|txt|json|pdf|png>	output format (default svg); json writes the Plan JSON that --from-json reads
--level <n>	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 <px>	page width hint in pixels
--scale, -s <n>	raster scale for the PNG backend (ignored by the non-raster formats)
--cols <n>	text renderer (-f txt / preview --ascii) grid width in characters (default 80)
--charset <unicode|ascii>	text renderer glyph set (default unicode)
--overlay <circulation>	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 <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

# recompile on every save (interactive; agents should use compile)
$ archlang watch plan.arch -o plan.svg

archlang validate

parse + resolve + lint, no render (is it valid & sound?)

Input: <file.arch|-> · 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 <graph.json>	also check the plan's interior-door adjacency against an intended graph (bare dict or {input_graph:{…}}); mismatch → exit 2
--intent <intent.json>	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 <CODE[,CODE…]>	show only diagnostics with these codes — a DISPLAY filter: the exit code and ok still come from the unfiltered set
--severity <error|warning>	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

# the ship gate: errors and advisory warnings both fail
$ archlang validate plan.arch --strict --json

# gate on a brief's intent contract and get per-violation correction prompts
$ archlang validate plan.arch --intent brief.json --feedback --json

# check interior-door adjacency against an intended room graph
$ archlang validate plan.arch --graph rooms.json --json

# read only the blocking errors; `ok` and the exit code still weigh every diagnostic
$ archlang validate plan.arch --severity error --json

archlang describe

semantic facts: rooms, areas, adjacency, what doors connect

Input: <file.arch|-> · Output: facts (JSON or a summary), narrowed by --room/--zone/--select/--level

Flag	Does
--room <id[,id…]>	keep only these rooms; doors/windows/openings/furniture narrow to the ones touching them (plan-level facts — bbox, totals, caption — stay whole-plan)
--zone <path[,path…]>	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 <key[,key…]>	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 <n>	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)
--facts <symmetry|syntax[,…]>	also compute these opt-in facts: symmetry (the plan's symmetry group per layer — shell, rooms, full — and its repeated rooms) and syntax (space-syntax depth, mean depth, RA, integration and control on the access graph); absent by default
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

Examples

# rooms, areas, adjacency, door connections, caption, freedom — confirm the plan means what you intended
$ archlang describe plan.arch --json

# describe source piped on stdin, no temp file
$ archlang describe - --json < plan.arch

# just the rooms and the totals — keep a big plan's facts inside a bounded context
$ archlang describe plan.arch --select rooms,totals --json

# only those two rooms and the doors/windows/furniture that touch them
$ archlang 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
$ archlang describe museum.arch --zone west --json

# the upper storey's rooms/areas/access as the top-level facts (`levels[]` carries every storey)
$ archlang describe house.arch --level 2 --json

# add the symmetry group per layer, repeated rooms, and space-syntax integration on the access graph
$ archlang describe plan.arch --facts symmetry,syntax --json

archlang score

continuous intent satisfaction (satisfied/total) as data — the refine-loop reward. Measures, never gates (validate --intent is the gate).

Input: <file.arch|-> · Output: { ok, satisfied, total, score, subscores, violations } (exit 0 on a successful measurement, even when assertions fail)

Flag	Does
--brief <intent.json>	the intent JSON to measure satisfaction against (required)
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

Examples

# continuous intent satisfaction as the refine-loop reward; always exits 0 on a measurement
$ archlang score plan.arch --brief brief.json --json

archlang lint

architectural soundness warnings

Input: <file.arch|-> · Output: W_* warnings (narrowed by --code/--severity; filtered/total_diagnostics mark a filtered result)

Flag	Does
--profile <residential-basic|accessibility-advisory>	advisory ruleset
--strict, --fail-on-warning	warnings fail (exit 2)
--code <CODE[,CODE…]>	show only diagnostics with these codes — a DISPLAY filter: the exit code and ok still come from the unfiltered set
--severity <error|warning>	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

# architectural soundness warnings as data, each with a fix
$ archlang lint plan.arch --json

# gate on the accessibility ruleset (any warning exits 2)
$ archlang lint plan.arch --profile accessibility-advisory --strict

# read only the reachability warnings; the exit code still reflects every diagnostic
$ archlang lint plan.arch --code W_ROOM_UNREACHABLE,W_NO_ENTRANCE --json

archlang ast

parse only (no resolve/render) and print the span-bearing AST as JSON

Input: <file.arch|-> · Output: AST JSON (scripting nodes unexpanded)

Flag	Does
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

Examples

# span-bearing parse tree with no resolve or render — locate a statement by byte offset
$ archlang ast plan.arch --json

archlang complete

completion items in scope at a source byte offset (the LSP completion() core)

Input: <file.arch|-> · Output: { items: [...] } completion items

Flag	Does
--at <byteOffset>	source byte offset to list completions at (required)
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

Examples

# what may legally be written at byte offset 120
$ archlang complete plan.arch --at 120 --json

# completions for source on stdin
$ archlang complete - --at 0 --json < plan.arch

archlang fmt

canonical formatting

Input: <file.arch|-> · 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

# canonical source plus a `changed` flag, nothing written
$ archlang fmt plan.arch --json

# rewrite the file in canonical form
$ archlang fmt plan.arch --write

archlang repair

explicit source-to-source corrector (furniture out of walls) + change log

Input: <file.arch|-> · Output: corrected source + change log on stderr

Flag	Does
--out, -o <file|->	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

# the geometric corrector: `source` + a `changes[]` log of every furniture move
$ archlang repair plan.arch --json

# write the corrected source to a new file
$ archlang repair plan.arch -o repaired.arch

archlang fix

apply the machine-applicable fix suggestions on a plan's diagnostics (bounded fixpoint)

Input: <file.arch|-> · Output: fixed source (to the input file or -o) + a unified diff and change log on stderr

Flag	Does
--out, -o <file|->	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

# preview the exact unified diff `fix` would write, changing nothing on disk
$ archlang fix plan.arch --dry-run

# the same preview as data: which fixes would be applied, plus the `diff` they produce
$ archlang fix plan.arch --dry-run --json

# apply the machine-applicable fixes in place, keeping the original as plan.arch.bak
$ archlang fix plan.arch --backup --json

# also apply the maybe-incorrect fixes, leaving the input untouched
$ archlang fix plan.arch -o fixed.arch --unsafe --json

archlang finish

furnish the rooms that hold no furniture, then add the sheet statements a plan lacks (paper, scale, dims auto, title, schedule rooms, legend); deletes nothing

Input: <file.arch|-> · Output: finished source (to the input file or -o) + a unified diff and change log on stderr

Flag	Does
--out, -o <file|->	output file for the finished source, or '-' for stdout (default: rewrite the input file in place)
--only <sheet|furnish>	run only this stage (available: sheet, furnish; default: furnish, then sheet)
--reissue	allow paper and scale (nothing else) to be replaced when the drawing does not fit the authored sheet
--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
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

Examples

# preview the furniture and sheet statements `finish` would add: `changes[]`, `unresolved[]` and the `diff`
$ archlang finish plan.arch --dry-run --json

# complete the drawing in place once lint is clean, keeping the original as plan.arch.bak
$ archlang finish plan.arch --backup

# preview only the furniture: one `furniture` statement per piece, and each room left empty with the reason
$ archlang finish plan.arch --only furnish --dry-run --json

# also replace a paper/scale the drawing does not fit, leaving the input untouched
$ archlang finish plan.arch --reissue -o issued.arch

archlang reroll

offer a proven-equivalent for loop for a repeated statement run

Input: <file.arch|-> · Output: suggestions (JSON or a summary), or the rewritten file with --write

Flag	Does
--write	apply every non-overlapping suggestion and re-verify the combined result's compiled SVG is byte-identical to the original before writing (no --dry-run/--backup: a failed re-verify writes nothing, and every suggestion is already proven byte-for-byte before it is offered)
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

Examples

# each candidate run as { span, replacement, count, loopVar, tokensBefore, tokensAfter }
$ archlang reroll plan.arch --json

# splice in every proven loop; { ok, wrote, target, applied, skipped } (wrote/target as in `archlang fix`)
$ archlang reroll plan.arch --write --json

archlang suggest

advisory topology suggestions as data (door/window statements that resolve reachability/window faults)

Input: <file.arch|-> · Output: suggestions (JSON or a summary)

Flag	Does
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

Examples

# ready-to-paste door/window statements for unreachable rooms, no entrance, or a windowless bedroom
$ archlang suggest plan.arch --json

archlang 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

# discover every command, flag, format, and error code in one call
$ archlang manifest --json

archlang 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

# the whole language on one page — read this before authoring
$ archlang spec

archlang 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 <spec|workflow|cli|errors>	print only one section of the bundle instead of all 113 KB of it (spec = the language, 30 KB; workflow = the agent loop, 24 KB; cli = every command, 22 KB; errors = the diagnostic catalog, 35 KB)
--json	structured result on stdout, messages on stderr

Examples

# the cold-start bundle: spec + workflow + CLI reference + every diagnostic
$ archlang context

# just the diagnostic catalog (35 KB) — read one section instead of paying for the whole 113 KB bundle
$ archlang context --section errors

archlang new (alias: init)

scaffold a starter .arch

Input: none · Output: starter source

Flag	Does
--out, -o <file|->	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

# get the starter plan as a `template` string, writing nothing
$ archlang new --json

# scaffold a starter file to edit
$ archlang new -o plan.arch

archlang explain

look up an error code (cause / fix / example)

Input: <CODE> · Output: catalog entry

Flag	Does
--json	structured result on stdout, messages on stderr

Examples

# the catalog entry for a diagnostic code: cause, fix, example
$ archlang explain E_ROOM_SIZE --json