CLI reference

The complete command-line contract: five subcommands, every flag, exit codes, diagnostics, and environment variables. Source: packages/cli/src/*.ts.

Synopsis

wit parse <file>
wit check <file>
wit fmt <file> [-w|--write]
wit build <file> [-o out.html|out.md|out.pdf] [--format html|md|pdf] [--raw | --fragment]
                  [--sources wit.sources.json --allow-exec] [--env .env]
wit tour <file>
wit --version | --help

Global

Global flags
Invocation	Result	Exit
wit --help or -h	usage text	0
wit --version or -v	prints 0.2.0	0
unknown command	help on stderr	2

wit parse

Parse a file and print its AST as pretty JSON. No flags.

parse
Outcome	Exit
prints AST JSON	0
parse error — diagnostic on stderr	1
missing file argument	2

wit check

Parse and resolve — a fast validity check. No flags. Does not expand or render; catches resolve-stage errors only.

check
Outcome	Exit
clean — prints ok and the path	0
any stage error	1
missing file argument	2

wit fmt

Structural re-indent. Prints to stdout by default.

fmt
Flag	Meaning	Default
-w or --write	write in place; prints formatted or unchanged	stdout
parse error	nothing written; exit 1	—

Preserves prose exactly and leaves raw double-at bodies, scripts, record and data values, and form-fill bodies verbatim. Missing file argument → exit 2.

wit build

The full pipeline: parse → load → resolve → expand → render.

build flags
Flag	Argument	Meaning	Default
-o or --out	a path	output file; format inferred from extension	stdout
--format	html or md or pdf	explicit format overriding inference	html
--fragment	none	bare wit-doc article only	off
--raw	none	full document with reset-only CSS	off
--sources	a json file	external-data source config	none
--env	a dotenv file	merged into the env source and child env	none
--allow-exec	none	permit running configured source programs	off

Format inference

Output format from extension
Extension	Format
.html or .htm	html
.md or .markdown	md
.pdf	pdf
anything else	E_UNKNOWN_OUTPUT_FORMAT — exit 1

--raw versus --fragment

If both are given, --fragment wins: the HTML options return early on fragment before checking raw. --fragmentemits <article class="wit-doc"> only; --raw emits a full document with a reset-only base for author-supplied styling; the default is a self-contained styled document (a Word-like house style).

PDF specifics

Requires -o <file.pdf>

an error, exit 1

. Drives a headless system Chrome or Chromium (candidate list in the source, or a WIT_CHROME override — the override wins with no fallback). Injects a base href (the document directory) so relative assets resolve; runs with a 60-second timeout; writes a temporary HTML then unlinks it. No Chrome → a helpful error, exit 1. Success → prints the written path.

wit tour

An indented AST tree plus an AST-coverage report.

tour
Flag	Meaning
--report	force report mode even on a non-TTY
--no-report	tree only — for piping
default	report on a TTY

The footer reports AST kinds seen: X/Y against the 24 known kinds, plus the paramsSource variants and NodeDef shapes seen. Overridable by WIT_TOUR_REPORT=1 / WIT_TOUR_NO_REPORT=1. Unknown flag → exit 2. Checked output lives in tests/integration/feature-tour.tour.txt.

Cross-cutting

Exit codes
Exit code	Meaning
0	success
1	stage or IO error
2	usage error

Environment variables
Env var	Effect
WIT_CHROME	PDF browser override — no fallback
WIT_DEBUG_COMMENTS=1	keep comments in the HTML render
WIT_TOUR_REPORT / WIT_TOUR_NO_REPORT	force tour report mode

All diagnostics use file:line:col: E_CODE: message. See the error catalogue.