CLI Reference

This page documents the Wist command-line surface used by the public examples. It is a practical reference for running source text, files, dialect files and canonical backend IDs from the repository checkout.

When to read this page

Read this after First Program when you want to run more than the smallest quick-start expression.

Command shape

From the repository root, Wist examples are run through the Wistc project:

dotnet run --project UniversalToolchain/Wistc/Wistc.csproj -- run [options] [code]

The -- separates dotnet run options from Wistc options.

Common options

Option	Meaning
--eval	Treats the positional code argument as an expression and prints the result.
--file path/to/program.wist	Runs a source file.
--dialect-file path/to/dialect.wistdialect	Uses an explicit dialect file instead of the default runtime surface.
--backend cil	Runs through the CIL backend when the selected dialect exposes cil.
--backend interpreter	Runs through the interpreter backend when the selected dialect exposes interpreter.
--list-modules	Lists available runtime components and exits.
--trace path/to/trace.json	Writes a redacted structured JSON trace for the run.

Only canonical backend IDs are accepted; compatibility aliases are not supported.

Debug trace

The current release supports a structured redacted trace artifact:

dotnet run --project UniversalToolchain/Wistc/Wistc.csproj -- run --eval "2 + 3 * 4" --backend interpreter --trace trace.json

The trace is JSON and redacts source text/runtime values by default. Schema wist-debug-trace/2 records source length/hash, dialect/backend selection, bounded coarse runtime stages and result or error summary. It does not restore logs.txt and it is not a full visual viewer yet.

Minimal expression

dotnet run --project UniversalToolchain/Wistc/Wistc.csproj -- run --eval "(2 + 2) * 3" --backend cil

Expected output:

12

In this command, --eval is a flag and "(2 + 2) * 3" is the positional source argument.

Interpreter mode should produce the same observable result when it is available:

dotnet run --project UniversalToolchain/Wistc/Wistc.csproj -- run --eval "(2 + 2) * 3" --backend interpreter

Running a program file

A file-based run combines a program file with an optional dialect file:

dotnet run --project UniversalToolchain/Wistc/Wistc.csproj -- run --dialect-file UniversalToolchain/Dialects/examples/wist/minimal-arithmetic/dialect.wistdialect --file UniversalToolchain/Dialects/examples/wist/minimal-arithmetic/program.wist --backend interpreter

Use this form for documentation examples, tests and local debugging because the program and dialect are both explicit.

Canonical backend IDs

Wistc and dialect files use the same IDs: cil and interpreter. There is no alias translation layer.

A dialect that exposes only interpreter should reject --backend cil. A dialect that exposes only cil should reject --backend interpreter. Silent fallback would hide composition errors.

Common failures

Symptom	Likely cause
Project path cannot be found	Command was run from the wrong directory. Run from the repository root.
CIL backend is rejected	The selected dialect does not expose the cil backend.
Interpreter backend is rejected	The selected dialect does not expose the interpreter backend.
Syntax is rejected	The dialect does not select the module that owns the syntax.
Interop expression is rejected	The selected dialect does not include trusted interop support.
Dialect file fails to parse	The file may use syntax from a secondary parser path instead of the runtime .wistdialect format.

Current dialect syntax reminder

Current shipped runtime dialect examples use compact comma-separated selection directives:

dialect MinimalArithmetic
use Arithmetic,Numbers,Scopes,Whitespaces
backend interpreter

For a CIL-capable dialect, select the cil backend id and request it from the CLI through --backend cil:

dialect MinimalArithmeticNative
use Arithmetic,Numbers,Scopes,Whitespaces,NativeTypes
backend cil
enable ArithmeticOptimization
enable NativeCilOptimization
enable NativeTypesOptimization

The repository also contains a stricter parser-specific dialect syntax, but public Wist runtime examples should follow the syntax used by shipped .wistdialect profiles unless the runtime path is intentionally migrated.

Next

Continue with Wist Syntax Tour or Minimal DSL.