CLI reference

The wit binary is both a tool and the model host implementation. Every embedding question — how to wire a data loader, how output paths are chosen — is answered concretely by the CLI's source. This page is the command

Commands

wit parse <file> — print the AST as JSON.
wit check <file> — parse, resolve, and expand; report errors only (non-zero exit on failure).
wit fmt <file> [-w|--write] — structural re-indent via format().
wit build <file> [options] — compile to HTML, Markdown, or PDF (see below).
wit tour <file> — a narrated walkthrough of the document.
wit --version / wit --help.

build

wit build <file>
  [-o out.html | out.md | out.pdf]
  [--format html | md | pdf]
  [--raw | --fragment]
  [--sources wit.sources.json --allow-exec]
  [--env .env]

The output format is inferred from the -o extension (.html or .htm → HTML, .md or .markdown → Markdown, .pdf → PDF) or set with --format. With no -o, the default is a styled HTML document on stdout.

--fragment — emit the bare <article> instead of a full page.
--raw — use rawThemeCss (the mechanical reset) instead of the house style.
PDF — renders document-mode HTML, then paginates with a discovered headless Chrome. WIT_CHROME overrides the binary; --no-pdf-header-footer drops the running header and footer.

The external-data host

The CLI is one implementation of the @load seam. envis built in — it returns the process environment (plus an optional --env dotenv file) as a record. Every other alias comes from wit.sources.json:

{
  "sources": {
    "downloads": {
      "run": ["node", "scripts/downloads.js"],
      "format": "json",
      "timeoutMs": 30000
    }
  }
}

format

is one of json, csv, tsv, lines, text, svg, or html — seven output formats, plus the built-in env.

The security boundary

Running an aliased program requires --allow-exec. A document can name only an alias, never a command — the command lives in wit.sources.json, which the document author does not control. That separation is the whole security model of the data host.

How captures reach the program

Two ways, both at once: {{name}} tokens are substituted into the run argv, and the full capture object is written to the program's stdin as JSON. CSV and TSV get a minimal header-keyed parse — no quoted fields.

Common mistakes

Expecting @load <alias> to run a program without --allow-exec — only env works unguarded.
Expecting quoted CSV fields to parse — the parser is minimal.