The CLI

Octant exposes four subcommands: translate, check, explain, and version.

octant translate <input.tex> [--output <out.dp>] [--spans <out.spans.json>]
octant check     <input.tex>
octant explain   <input.tex> --target <id>
octant version

Any input path may be -, which reads LaTeX from standard input.

translate

translate is the main entry point. It runs the full pipeline, tokenize, parse, normalize, type-infer, emit, and writes a Deep .dp file plus a .spans.json provenance manifest.

octant translate input.tex --output out.dp --spans out.spans.json

When --output and --spans are omitted, the paths default to the input stem with the .tex extension replaced: input.tex produces input.dp and input.spans.json alongside it.

Translate flags

Flag	Effect
--output <file>	Deep .dp output path. Defaults to <input>.dp.
--spans <file>	Spans manifest path. Defaults to <input>.spans.json.
--inline	Write Deep to stdout and the spans manifest to stderr. No filesystem writes.
--no-spans	Skip the spans manifest. Smaller output, no provenance.
--config <file>	A TOML file of extra function mappings. See Extending Octant.
--wrap-as-function <name>	Emit a single function definition instead of per-equation bindings.
--params <p1,p2,...>	Explicit parameter list for --wrap-as-function.
--emit-nautilus <mode>	Emission mode for Nautilus references: stub (default) or access.
--input-encoding <enc>	Input encoding. Only utf-8 is accepted.

--inline

--inline writes the Deep to stdout and the spans manifest to stderr, with no files written. It is the form to pipe into a downstream Chelis command. Combine it with --no-spans to suppress the manifest on stderr.

octant translate input.tex --inline

--wrap-as-function

By default, translate emits each top-level LaTeX equation as a top-level Chelis Deep value binding. That faithfully mirrors the LaTeX shape, but the result is not self-typecheckable when the equation references free variables that are declared via % chelis: annotations but never bound by an earlier equation.

--wrap-as-function <name> re-shapes the emission as a single function-definition Deep tree. Every preceding equation in the file becomes a let binding. The final equation's body becomes the function body. The wrapper-introduced nodes (def, fn, params, let, bind) carry a reserved synthesized-marker span. Octant-translated body nodes keep their LaTeX-derived span identifiers verbatim, so the audit chain is unaffected.

octant translate references/black_scholes_call_function.tex \
  --wrap-as-function call_price \
  --output call_price.dp

When --params is omitted, the parameter list is taken from every % chelis: declaration whose name is not bound by an equation, in source order. --params <comma-list> sets the parameter list explicitly. Each named parameter must carry a % chelis: <name> : <type> annotation in the input so the wrapper can record its type.

--emit-nautilus

Some LaTeX names map to functions that live in Nautilus modules, for example \Phi to Nautilus.Distributions.normal_cdf. The --emit-nautilus flag controls how those references are emitted.

• stub (default): Octant inlines a local identity-stub def for each distinct Nautilus reference and rewrites call sites to a bare name. The emitted Deep is self-contained and compiles through the Chelis Deep build path. The stub returns its first argument unchanged, so the generated code is a numerical placeholder until it is linked against a real Nautilus implementation at deploy time. Octant prints a loud warning to stderr whenever it inlines a stub.
• access: emit the access-chain callee form, (access (access (var Nautilus) Distributions) normal_cdf). Useful for callers that resolve the Nautilus package through a Chelis-side build pipeline.

See Provenance and span tracking for the details.

check

check runs the pipeline up to and including type inference, writes no output, and exits with a code that reflects the outcome. It is the form to run in continuous integration to confirm a formula parses and type-infers cleanly.

octant check input.tex

explain

explain takes a Deep node identifier, the kind recorded in the spans manifest, and prints the LaTeX it came from.

octant explain input.tex --target eq:bs_002

The output reports the byte range, the line and column position, the literal source slice the span covers, the equation label if present, and a few lines of surrounding context with the matched line marked. If the target identifier is not in the manifest, explain reports the error and lists the first valid identifiers so you can pick a real one. Translate first to produce the manifest, then read identifiers from it.

version

version prints the Octant version string.

octant version

Exit codes

Every command maps its outcome to one of these exit codes:

Exit	Category	Meaning
0	success	the command succeeded
1	parse	LaTeX failed to tokenize or parse
2	type	type inference rejected the program
3	unsupported	a LaTeX construct outside the supported subset
4	io	a filesystem or stdio failure
5	encoding	the input bytes are not valid UTF-8, or an unsupported encoding was requested

The Scope and limitations chapter groups the errors by exit code, with the message and the fix for each.

Encoding

Octant reads UTF-8. The --input-encoding flag accepts only utf-8 (with utf8 as an alias); any other value exits with the encoding code. Convert other encodings to UTF-8 before translating, for example with iconv.