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

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.

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 <format> 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: <file.arch|-> (Plan JSON with --from-json) · Output: file (or stdout with -o -)

Flag	Does
--out, -o <file|->	output destination ('-' = stdout)
--format, -f <svg|dxf|txt|pdf|png>	output format (default svg)
--width, -w <px>	page width hint in pixels
--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
--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

arch 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 (default: alongside each input)
--format, -f <svg|dxf|txt|pdf|png>	output format (default svg)
--jobs, -j <n>	max concurrent renders (default: CPU count)
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

arch 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 destination
--format, -f <svg|dxf|txt|pdf|png>	output format (default svg)
--error-svg	on a broken plan, still emit a self-describing error-card image listing the diagnostics (exit code stays 2)
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

arch 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>	PNG destination (default: <name>.png)
--scale, -s <n>	raster scale (default 2)
--ascii	print a zero-dependency ASCII text plan to stdout instead of a PNG
--cols <n>	text renderer (-f txt / preview --ascii) grid width in characters (default 80)
--charset <unicode|ascii>	text renderer glyph set (default unicode)
--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
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

arch watch

recompile on save (interactive)

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

Flag	Does
--out, -o <file|->	output destination ('-' = stdout)
--format, -f <svg|dxf|txt|pdf|png>	output format (default svg)
--width, -w <px>	page width hint in pixels

arch 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)
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

arch describe

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

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

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

arch 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

arch lint

architectural soundness warnings

Input: <file.arch|-> · Output: W_* warnings

Flag	Does
--profile <residential-basic|accessibility-advisory>	advisory ruleset
--strict, --fail-on-warning	warnings fail (exit 2)
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

arch 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

arch 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

arch 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

arch 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 destination ('-' = stdout)
--json	structured result on stdout, messages on stderr
--quiet, -q	suppress human messages on stderr

arch 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) + change log on stderr

Flag	Does
--out, -o <file|->	output destination ('-' = stdout)
--unsafe	also apply maybe-incorrect fixes (default: machine-applicable only)
--dry-run	compute the result but do not write it
--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

arch 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

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

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

arch context

print the full bundled agent context (spec + workflow + CLI + errors)

Input: none · Output: the full agent context (llms-full.txt)

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

arch new (alias: init)

scaffold a starter .arch

Input: none · Output: starter source

Flag	Does
--out, -o <file>	write the starter here
--force	overwrite an existing file
--json	structured result on stdout, messages on stderr

arch explain

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

Input: <CODE> · Output: catalog entry

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