mclc CLI Reference

mclc is the MatrixScript compiler CLI. It wires together the MCL runtime packages (lexer, parser, validator, canonical, interpreter) and drives the 6-stage compilation pipeline defined in core/pipeline.mtx.

Source file: cmd/mclc/main.go.

Commands

Command	Description
`compile`	Compile a SKILL.mtx against user prose to produce an Intent IR
`validate`	Validate a `.mtx` file against spec rules
`hash`	Print the canonical AST hash (D11 mtx_digest)
`parse`	Parse a `.mtx` file and print an AST summary

mclc compile

Compiles a SKILL.mtx against user prose and produces a structured JSON output.

mclc compile -skill <path> -prose "user's goal" [flags]

Flags:

Flag	Type	Default	Description
`-skill <path>`	string	(required)	Path to the SKILL.mtx file
`-prose "text"`	string	(required)	User's natural language goal
`-verb <verb>`	string	(auto)	Pre-classified verb (skips stage 2)
`-grammar <id>`	string	`intent_frame@1`	Grammar constraint ID
`-confidence <f>`	float	`1.0`	Current confidence score
`-model <model>`	string	(registry)	Model string override
`-seed <int>`	int	`42`	Seed for D11 determinism
`-dry-run`	bool	`false`	Show interpolated prompts without calling LLM

Additional slot pre-fills can be passed as slot=value arguments.

Output (JSON):

{
  "mtx_digest": "sha256 hex of the SKILL.mtx AST",
  "matched_condition": "verb=build",
  "executed": true,
  "frame_json": "{...}",
  "prompt_messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."}
  ],
  "slots": [
    {"name": "target", "value": "...", "status": "resolved", "type": "ArtifactRef"}
  ],
  "unknowns": [
    {"slot_name": "target", "severity": "blocking", "reason": "..."}
  ],
  "clarify_questions": [
    {"slot_name": "target", "prompt": "Which artifact?", "type": "ArtifactRef", "required": true}
  ]
}

Slot statuses: empty, raw, resolved, default.

mclc validate

Validates one or more .mtx files against the spec rules.

mclc validate <path> [<path> ...]

The validator automatically detects whether a file is a SKILL.mtx (contains a SKILL section) or a core module and applies the appropriate rule set.

Exit codes:

Code	Meaning
0	All files valid
1	Validation errors (printed to stderr)

Example:

$ mclc validate skills/writing-plans/SKILL.mtx core/verb.mtx
skills/writing-plans/SKILL.mtx: ok
core/verb.mtx: ok

mclc hash

Prints the canonical AST hash for one or more .mtx files. This is the mtx_digest that flows into the D11 seed.

mclc hash <path> [<path> ...]

Output format:

<sha256 hex>  <path>

Example:

$ mclc hash skills/writing-plans/SKILL.mtx
a1b2c3d4e5f6...  skills/writing-plans/SKILL.mtx

mclc parse

Parses a .mtx file and prints a summary of its AST structure.

mclc parse <path> [<path> ...]

Output:

skills/writing-plans/SKILL.mtx: 8 sections
  SKILL: 8 entries
  INPUTS: 2 entries
  PROCEDURE: 3 entries
  OUTPUTS: 1 entries
  TOOLS: 1 entries
  SUB_SKILLS: 1 entries
  FAILURE_MODES: 2 entries
  HASH: 3 entries

Environment variables

Variable	Purpose
`FIREWORKS_API_KEY`	API key for Fireworks AI (compiler model)
`TOGETHER_API_KEY`	API key for Together AI (compiler model)

When no API key is available and -dry-run is not set, mclc compile falls back to dry-run mode automatically and prints a notice to stderr.

LLM integration

In compile mode, mclc creates an LLM client via llm.DefaultCompilerModel() (or the -model override). The client uses GrammarJSONSchema mode with the intent_frame@1 grammar to constrain the compiler model's output to valid Frame JSON.

The compiler model runs at temperature=0 with seed=42 by default for D11 determinism. The interpreter.Run method drives the 6-stage pipeline, making LLM calls at stages 2 (classify) and 3 (frame extract).