Install the CLI with Homebrew on macOS, use @linguacode/cli through npm or npx, or build it from source. Pin a version for automation.
This reference follows the same structured catalog used to generate lingua --help. The website build fails if its committed catalog snapshot drifts from the CLI source.
Commands
| Command | Purpose |
|---|---|
lingua utility <utility-id> |
Run one shared developer-utility adapter. |
lingua capsule validate <file> |
Validate a RunCapsuleV1 without execution. |
lingua capsule replay <file> |
Verify and replay a trusted single-source Capsule. |
lingua capsule verify <file> |
Strict captured-source comparison; source-build / unreleased command. |
lingua repro pack <capsule> --entry <path> |
Wrap a JavaScript Capsule and chosen files into a reproduction envelope; experimental. |
lingua repro review <envelope> |
Show what a reproduction asks for and its approval token; executes nothing. |
lingua repro run <envelope> --approve <token> |
Run an approved reproduction in a containment backend, or refuse; experimental. |
lingua run <file-or-directory> |
Execute a source file or conventional project root. |
lingua list utilities |
Print the live utility registry. |
lingua completion [bash|zsh|fish|install] |
Detect and install completions, or generate one shell script. |
lingua --version |
Print the build-time CLI version. |
lingua --help |
Print terminal help. |
Options
| Option | Used by | Meaning |
|---|---|---|
--input <file> |
utility |
Read utility input from a file instead of stdin. |
--option key=value |
utility |
Repeat to pass adapter-specific options. |
--stdin <file> |
run |
Forward file contents as program stdin. |
--timeout <ms> |
run, capsule replay, capsule verify |
Stop after 100–300000 ms. |
--env NAME=value |
run, capsule replay, capsule verify |
Repeat to add an explicit environment value. |
--entry <path> |
repro pack |
Relative .mjs or .cjs path the capsule source is staged at. |
--file <path> |
repro pack |
Repeat to add a supplemental file, relative to --root. |
--node <major> |
repro pack |
Node.js major the reproduction requests. |
--approve <token> |
repro run |
Approval token printed by repro review. |
--json |
data-producing commands | Emit one structured JSON document. |
--quiet |
data-producing commands | Suppress Lingua diagnostics, not command output. |
--yes |
completion |
Approve detected completion changes without prompting. |
--dry-run |
completion |
Show detected shells and target files without writing. |
--color <auto|always|never> |
all commands | Control human diagnostic styling. |
-- |
run |
Forward every remaining token to the program. |
--help, -h |
all commands | Show help. |
--version, -v |
top level | Print the CLI version. |
Exit codes
| Code | Name | Meaning |
|---|---|---|
| 0 | ok |
Command completed successfully. |
| 1 | userInputError |
Arguments, input, file, or shape are invalid. |
| 2 | runtimeError |
Execution failed, timed out, stopped, or exited non-zero. |
| 3 | unsupportedCapability |
Runtime, mode, toolchain, or output is unsupported. |
| 4 | internal |
An unexpected exception reached the CLI boundary. |
| 5 | verificationFailed |
Strict verification detected drift. |
| 6 | verificationInconclusive |
Evidence cannot establish a strict pass. |
Output contract
Human failures use a grep-friendly form:
lingua run: error[missing-runtime]: Required runtime "lua" is not available on PATH.
With --json, the same stable reason moves to stdout:
{
"ok": false,
"reason": "missing-runtime",
"detail": "Required runtime \"lua\" is not available on PATH."
}
Command-specific success envelopes are documented in the task guides. Existing exit codes are never renumbered.
Strict captured-source verification (unreleased)
lingua capsule verify <file> --timeout <ms> --env NAME=value --json is available in CLI 1.6.0 and later; on older installs check lingua capsule verify --help first. It compares status, stdout and stderr exactly; it does not verify a modified target file, security, hermetic execution or equivalence between engines. Only complete successful text baselines are supported, and Python, Go and web Ruby recordings are inconclusive because the app engine differs from the CLI runtime. ok is true only for verdict pass; drift exits 5 and inconclusive evidence exits 6. Input, capability, runtime and internal errors retain codes 1–4. Replay keeps its existing execution-only exit semantics.
Regression cases (unreleased/source builds)
lingua capsule verify <file> --target <file> --json
lingua capsule verify-suite <suite> --root <directory> --json
--target <file> runs the current saved relative file exactly like captured source (baseline runtime mode and working directory); --root <directory> constrains suite targets and defaults to cwd. Suite v1 embeds complete unchanged baselines, runs at most 20 cases/4 MiB serially with a five-minute total budget, and reports per-case strict verdicts. Import/preview never executes. Available in CLI 1.6.0 and later.
Permissioned reproductions (experimental, source builds)
lingua repro pack <capsule> --entry main.mjs --file lib/sum.mjs --root <directory> > repro.json wraps a JavaScript Capsule and chosen files into an envelope that denies network and allows only disposable writes. A file that a symbolic link takes outside the root, or that is not UTF-8, is refused. lingua repro review repro.json checks every hash, lists the required controls and prints an approval token without executing anything. lingua repro run repro.json --approve <token> --json runs the reviewed bytes under macOS Seatbelt with no network, no child processes and writes only to scratch and output, then compares the output exactly with the capsule: exit 0 for a match, 5 for a mismatch or denial, 6 for missing evidence. It refuses before launch on a stale approval (exit 1), a different Node.js major, a missing backend or an unenforced control (exit 3). Denials are not observable on macOS, so compliance reads not-observed, never clean.