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 backend aliases 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 compiler	Runs through the user-facing compiler alias when the selected dialect exposes CIL.
--backend interpreter	Runs through the interpreter backend alias when the selected dialect exposes the interpreter backend.
--list-modules	Lists available runtime components and exits.
--trace path/to/trace.json	Writes a redacted structured JSON trace for the run.

compiler is a user-facing backend alias. In dialect files, the backend id is usually cil.

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 compiler

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.

Backend alias versus dialect backend id

Wistc accepts backend aliases such as compiler and interpreter. Dialect files select backend ids such as cil and interpreter.

The mapping is intentional:

CLI backend alias	Dialect backend requirement
compiler	selected dialect exposes cil
interpreter	selected dialect exposes interpreter

A dialect that exposes only interpreter should reject --backend compiler. 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.
Compiler backend alias is rejected	The selected dialect does not expose the cil backend.
Interpreter backend alias 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 compiler:

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.