> Markdown rendition of https://typeglish.dev/docs/cli ("Commands — TypeGlish docs"). Canonical page: https://typeglish.dev/docs/cli · All pages: https://typeglish.dev/docs/llms.txt

Reference

# Commands

The `typeglish` bin runs the whole loop — check, score, test, build, deploy — and prints the language reference.

## Commands

The `typeglish` bin — author → check → score → test → build → deploy.

| Command | What it does |
| --- | --- |
| `typeglish sync [<folder>] [--connect <details>] [--origin <url>] [--port <number>]` | connect a playground session with --connect, or explicitly pair a local prompt folder; keep running for live two-way sync. |
| `typeglish annotate <file> [--refresh] [--fix\|--check] [--json]` | add missing statement explanations; --refresh explicitly replaces existing notes. |
| `typeglish cleanup <file> [--fix\|--check] [--json]` | format and apply declared-safe repairs; leaves wording and annotations unchanged. |
| `typeglish refine <file> [--fix\|--check] [--json]` | refine supported statements while preserving authored annotations. |
| `typeglish compress <file> [--fix\|--check] [--json]` | shorten supported statements, reduce rhetorical emphasis and consolidate repeated guidance. |
| `typeglish consolidate <file> [--fix\|--check] [--json]` | remove proven repeated standing guidance while retaining source evidence. |
| `typeglish analyze <file> [--json]` | synchronous authoring report: diagnostics, statement explanations, TG score and |
| `typeglish statements <file> [--line <n>\|--statement <id>] [--json]` | read-only shared statement report (enrichment: 32000 chars, 4000/line, 512 statements). |
| `typeglish prepare-rewrite <file> [--history <json>] [--json]` | prepare compact source-bound rewrite context for your agent. |
| `typeglish brief-rewrite <file> [--group <id>] [--group-offset <n>] [--statement-offset <n>] [--diagnostic-offset <n>] [--limit <n>] [--history <json>] [--json]` | inspect bounded related-statement groups, exact redundancy candidates and owner decisions. |
| `typeglish review-rewrite <file> --candidate <file> --baseline <json> [--mapping <json>] [--history <json>] [--json]` | review a candidate against the prepared source/configuration snapshot. |
| `typeglish import <file> [--out <path>] [--json]` | convert an existing prompt to .tg — deterministic: repairs FORM (never words), |
| `typeglish check <file\|dir...> [check options]` | validate; exits 1 when any file has a blocking error. A directory expands to its |
| `typeglish build <file\|dir...> [build options]` | compile passing files to artifacts + record the manifest. A directory builds |
| `typeglish score <file> [--min B\|80] [--json]` | the deterministic TG score; exits 1 below --min |
| `typeglish review <file> [--min B\|80] [--json]` | one run, one report: the grade and the grade PROJECTED if every fix lands, the fixes ranked by |
| `typeglish fmt <file\|dir...> [--check]` | mechanical formatting, in place: join hard-wrapped fragments, split compound rules, |
| `typeglish test <file...> [test options]` | run the file's $TEST suite — --dry is offline (validate + coverage); |
| `typeglish resolve <file> [--vars '<json>']` | apply conditionals, print the resolved SOURCE (a .tg — |
| `typeglish reference` | print the language reference (agents: read this first) |
| `typeglish mcp` | serve check/build/score/review/statements/brief-rewrite/prepare-rewrite/review-rewrite/explain/reference over MCP stdio |
| `typeglish lsp` | serve the language server over stdio — diagnostics, semantic tokens, hover, completion, rename — for any LSP editor |

## Flags

Flags grouped by the command they modify.

| Flag | What it does |
| --- | --- |
| `--fix` | apply the declared-safe fixes in place first (whitespace, the character set, terminators — never · check |
| `--no-program` | skip the cross-file program pass on directory targets — every file checks alone · check |
| `--out-dir <dir>` | artifact directory (default: .typeglish/dist) · build |
| `--vars '<json>'` | input bag — conditionals compile away; omitted = template build (unbound switches · build |
| `--bundle` | also write <artifact>.agent.json — the $CONFIG / $TOOL agent bundle · build |
| `--dry` | fully offline: validate the suite + report rule coverage, zero model calls · test |
| `--no-judge` | deterministic asserts only — skip the judge on prose expectations (still generates) · test |
| `--model <id>` | the model that answers each case (and judges, unless --no-judge) · test |
| `--prepare` | run statement preparation after raw-prompt conversion (split, clean up, annotate); · import |
| `--out <path>` | output path (default: the input with a .tg extension, beside it; for a .vf export, a · import |
| `--diff` | show the repairs as a unified diff (show, don't count) · import |
| `--gate` | exit non-zero when errors would block `typeglish build` (for CI and agents) · import |
| `--fix-citations` | apply the reported $REQUIRE section lines (placed below any $CONFIG block). The flag · import |
| `--check` | report files that WOULD change and exit 1 — writes nothing (the CI mode) · fmt |
| `--connect <details>` | sync: connect automatically using details from a playground agent prompt (no time limit); replaces --origin/--port · global |
| `--agent <name>` | sync: identify the coding agent displayed by the connected playground · global |
| `--origin <url>` | sync: exact allowed playground origin (default https://typeglish.dev) · global |
| `--port <number>` | sync: local port (default 0, automatically allocated) · global |
| `--history <json>` | rewrite commands: source-bound authoring trace or pipeline result; review also reads history from its saved baseline envelope · global |
| `--group <id>` | brief-rewrite: inspect a group ID from the current source/configuration snapshot · global |
| `--group-offset <n>` | brief-rewrite: zero-based offset in the inspection group queue · global |
| `--statement-offset <n>` | brief-rewrite: zero-based offset within the selected group · global |
| `--diagnostic-offset <n>` | brief-rewrite: zero-based offset within all distinct diagnostics for the selected group · global |
| `--limit <n>` | brief-rewrite: page size from 1 to 20 (default 5) · global |
| `--candidate <file>` | review-rewrite: proposed source file to inspect without applying it · global |
| `--baseline <json>` | review-rewrite: saved preparation envelope or source/configuration snapshot JSON · global |
| `--mapping <json>` | review-rewrite: optional array of sourceIds/candidateIds/reason provenance groups · global |
| `--line <n>` | statements: inspect a one-based physical source line (not its display label) · global |
| `--statement <id>` | statements: inspect an occurrence ID from the current source/configuration snapshot · global |
| `--refresh` | annotate: explicitly refresh existing repairable annotations instead of adding missing ones · global |
| `--strict` | escalate every IMPORTANT finding (correctness defects) to a blocking error · global |
| `--json` | machine-readable output on stdout (agents: parse this, not the text) · global |
| `--vars` | a JSON object of input values, e.g. '{"tier":"premium"}' · global |
| `--min` | score floor — a grade (A–F) or a number, the CI gate; for `test`, the 0..1 rubric pass floor · global |
| `--explain <code> [file]` | what a diagnostic code or score facet means (e.g. logic/contradiction, enforceability); · standalone |
| `--version` | print the compiler version · standalone |
| `--help` | this text · standalone |