CLI reference
Every wit subcommand, flag, exit code and environment variable.
Source: packages/cli/src/.
Synopsis
wit parse <file> wit check <file>… [--template name] [--sources wit.sources.json --allow-exec] [--env .env] wit fmt <file> [-w|--write | --check] wit build <file> [-o out.html|out.md|out.pdf] [--format html|md|pdf] [--raw | --fragment] [--template name] [--paper a4|a5|letter|legal] [--sources wit.sources.json --allow-exec] [--env .env] wit tour <file> [--report | --no-report] wit tokens [--parser] <file> | -e <source> wit migrate <file|dir>… [-w|--write] wit --version | --help
| Exit | Meaning |
|---|---|
| 0 | success |
| 1 | a stage or file error |
| 2 | bad usage — an unknown command or flag or a missing file |
wit build
The full pipeline: parse → load → resolve → expand → render. Definitions in every referenced file are scanned first, so a use of a definition from another file needs no close there either.
| Flag | Meaning | Default |
|---|---|---|
| -o or --out PATH | write to a file; format from the extension | stdout |
| --format html|md|pdf | set the format explicitly | html |
| --fragment | only the article element | off |
| --raw | full page with a reset-only stylesheet | off |
| --template NAME | build with a bundled template instead of the one referenced | none |
| --paper a4|a5|letter|legal | page size; beats the template's | the template's |
| --sources FILE | external-data source config | none |
| --env FILE | dotenv merged into the env source and child processes | none |
| --allow-exec | allow running configured source programs | off |
| Extension | Format |
|---|---|
| .html or .htm | html |
| .md or .markdown | md |
| anything else | E_UNKNOWN_OUTPUT_FORMAT — exit 1 |
- Default HTML is a self-contained page with the bundled theme. With both
--fragmentand--raw,--fragmentwins. - Relative asset paths (
src,href) in a referenced file are rebased to the file you build, when the asset lives beside the referenced file. - PDF needs
-o file.pdfand a system Chrome or Chromium (WIT_CHROMEoverrides the search, with no fallback). Wit writes a temporary HTML with a<base href>so assets resolve, prints with a 60-second timeout, and fails — rather than leave a stale PDF — if no PDF is written.
wit check
Runs the same pipeline as build without rendering — a faithful dry
run, including @load when given the same data flags. Takes several
files and reports the first error in each.
| Outcome | Output | Exit |
|---|---|---|
| all clean | ok: FILE per file | 0 |
| any file fails | the diagnostic on stderr | 1 |
| no file or unknown flag | usage on stderr | 2 |
wit fmt
Re-indents a file to match its nesting without changing what it renders. Prose, raw bodies, scripts and data values stay as written. One file at a time.
| Flag | Effect | Exit |
|---|---|---|
| none | formatted source to stdout | 0 |
| -w or --write | write in place; prints formatted FILE or unchanged FILE | 0 |
| --check | write nothing; exit 1 and name the file if it would change | 0 or 1 |
| parse error | nothing written | 1 |
wit migrate
Rewrites Wit 0.2 syntax as 0.3 — pipes, capture lists, { … } calls, space-separated params, colon-scatter, form-fill uses, ..., key - value and equals. Directories are searched
for .wit files (skipping node_modules, dist and dot-folders). Each file is migrated against the
definitions in it and every file it references.
| Call | Effect |
|---|---|
| one file | print the migrated source |
| several files or a directory | list each FILE: needs migrating |
| -w or --write | rewrite changed files in place |
| a construct it cannot rewrite | FILE:LINE:COL: warning: … on stderr |
Exit 1 if any file fails to read or lex; 2 with no path.
wit migrate chapters/ -w wit check chapters/*.wit
wit parse
Prints the AST as JSON. Exactly one file, no flags. See AST reference.
wit tokens
Prints the token stream, one token per line: position, kind, payload, source
text. --parser shows the stream the parser walks, after stray
markers are turned back into prose. -e takes source inline; \n in it is a newline. Use it to see why a piece of prose became
structure, or did not.
wit tokens --parser -e 'See (a(href: /x) the site a) and (a few notes).'
wit tour
An indented AST tree plus a coverage footer: AST kinds seen out of 24, the paramsSource variants (parens, none)
and the definition shapes. The footer shows on a TTY; --report / --no-report force it on or off.
Environment
| Variable | Effect |
|---|---|
| WIT_CHROME | browser for PDF output — no fallback |
| WIT_DEBUG_COMMENTS=1 | keep comments in HTML output |
| WIT_TOUR_REPORT=1 / WIT_TOUR_NO_REPORT=1 | force the tour footer on or off |