Write and check
The commands you use while you write a model: check it, fix it and format it.
Commands: archec check · archec fix · archec explain · archec suggest · archec vet · archec fmt · archec edit · archec review · archec live-fix · archec mcp · archec convert-handlers · archec stubs · archec patterns · archec ast
On this page: Code scanning (SARIF) · More on these commands
| Command | What it does |
|---|---|
archec check <main.arche>… [--json] [--strict] [--quiet] [--beginner] [--core] [--sarif <report.sarif>] |
Lint: errors, warnings, hints, each with its code ([unresolved], [suspect], [rule]…). Exit 1 on an error; --strict also on a warning. --sarif: the same diagnostics as SARIF 2.1.0, for code scanning (below). The project's own rules and the links made suspect by a reworded requirement are part of it. --beginner (or ARCHE_LEVEL=beginner): the common messages in plain words, with what exists (“You used bar but b has no port called that. Its ports are: cmd, st.”), and how many archec fix can fix (fixes). --core: also an error (not-core) for each declaration or property of the project's own files outside the 1.0 core, naming the extension it belongs to (core); with none, it says how many core concepts the model uses. |
archec fix <main.arche> [--dry-run] [--only code,…] [--vet] [--json] |
Errors that fix themselves: the preferred fix of each diagnostic (the closest name, property, value or unit, the link's ends swapped, a port's direction, a ; before a glued property, a file an include names…), one per place, then checked again — until none applies (5 passes at most). Prints each fix and the diff; --dry-run writes nothing. The fixes that guess content or remove something (an unused declaration, a placeholder text) are the editor's to offer, not applied — unless --only names their code. Style findings only with --vet. A pass that adds errors is retried fix by fix, keeping only those that add none. See fixes. |
archec explain [<code>| <area>] |
What a diagnostic code ([naming], [unresolved]…) means, and the style guide's section on it. With no code, the areas the codes fall into (parse, names, types, links, timing, safety, style…); archec explain timing lists an area's codes, one line each; a near miss gets a did-you-mean. Long messages are cut after their first sentence in the terminal; --long prints them whole. The last line is the code's page on arche-lang.xyz (/docs/errors/<code>/), the page the editor links to. --json prints the whole catalog: every code with its area, severity, summary and automatic fix. |
archec review <main.arche> [--threshold 0.3] [--suggest] [--dry-run] [--json] [--model id] |
Advice from Claude (claude-opus-5-5) on the traces. The checker knows both ends of a trace exist, not whether the link makes sense: this asks, one judgment per trace from what the two elements say about themselves (and the trace's rationale), and lists those below the threshold. --suggest also lists parts that very likely satisfy a requirement with no trace saying so. It is advice, kept apart: nothing of it reaches check, ci or a build, and the answers are not reproducible. It sends model text out: the kind, id, name and texts of each traced element go to the Anthropic API, only when this command runs; --dry-run prints the requests and sends nothing. Credentials: ANTHROPIC_API_KEY, or ant auth login. A refused request falls back to another model on the server side. Offline by default: archec config ai online (or ai local-ai) lets it send (ai-engineering.md). |
archec live-fix <ID> [main.arche] [--state .arche/live.json | --replay <trace>… [--deployment D]] [--dry-run] [--json] [--model id] |
Explain & fix: why a requirement, chain, thread or container that archec live sees failing fails, and the edits to the .arche files that would fix it, from Claude (claude-opus-5-5). It reads the latest live state (.arche/live.json beside the main file, which archec live rewrites at each refresh; --state another; --replay runs archec live --replay on the traces to their end), and sends the item, its evidence, what was measured and what archec analyze predicts of the chains, threads and containers involved, and their declarations with file and line. Each proposed edit replaces text found at its line (or within 5 lines); the others are dropped with the reason. --json: {explanation, edits: [{file, line, col, endLine, endCol, old, new, why}], rejected, notes}, what the VS Code extension applies as a previewed edit. Advice, like review: it sends model text out, only when this command runs; --dry-run prints the request and sends nothing. Offline by default: archec config ai online (or ai local-ai) lets it send (ai-engineering.md). |
archec mcp |
The compiler as a Model Context Protocol server on stdio, for AI agents. Its tools are the commands, one to one: check (diagnostics as JSON), fix (the fixes of each diagnostic as edits by line and column; apply: true applies the preferred ones as archec fix), explain, describe (the language reference of a keyword), outline (the declarations, nested, with file and line), brief (one part's context before changing it, as archec brief; task: true writes .arche/task), analyze, format, diff, generate, build, and for a running system live_status (what archec live sees: .arche/live.json, or a replay of the traces given) and live_explain (the request archec live-fix would send — or, with send: true, Claude's answer). To tune a controller on the simulator (tuning): scenario_list (the test cases and the tunables), sim_run (the cases run: pass or fail, a score, the failed checks with their values; values tries tunables without writing them; each run a try in .arche/tries/), sim_observe (signals sampled at times), params_get and params_set (written into the source, checked, marked as an AI's edit). Paths are relative to the directory it runs in. The agent edits the .arche files itself and calls check: the compiler stays the judge. In Claude Code: claude mcp add archec -- archec mcp. |
archec suggest <main.arche> [--json] |
What the store's shelves already have for what the model writes by hand, each with where, what it looks like, why, and the exact lines to add (uses, include). A function or a component whose name or body looks like one of the algorithms: pid in the name, or integral with kp/ki; debounce; moving_average, or a sum over a window; y += a * (x - y) (low-pass); a CRC polynomial (0x1021, 0xEDB88320); and the others by name. A message or a struct whose fields are an arche-types type: x, y, z is Vec3 (Point3 in m), w, x, y, z Quaternion, lat/lon GeoPoint, r, g, b RgbColor… — with the replacement (message ACCEL: Vec3) when the field names and types are the very same. A component whose name is a store device's (Bme280Sensor). What already requires the algorithm's interface, or extends a library's component, is left alone. Nothing is changed: archec shelf add or archec device add adds a piece; the editor shows the same as quiet hints (the editor). |
archec vet <main.arche>… [--json] |
Style, as go vet: long forms, property order and groups, declarations out of their set, naming. archec check leaves these out (--vet shows them there too). Exit 1 on a finding; archec fmt --write fixes the layout ones. |
archec fmt <file.arche>… [--write|--check] [--simplify] [--extract-code[=file.ts|file.py]] |
Format (to stdout, or in place with --write; --check fails when a file is not formatted). --simplify rewrites the long forms in the short ones, with the same meaning; --extract-code moves the ```ts (or ```python) blocks into .ts (.py) files: one per component, in its language, or all in the file named. --edition 0.12: the project then says the edition it is written in (edition "0.12"), in which the old spellings are errors. |
archec edit <main.arche> <element-id> [--set <key> <value>]… [--unset <key>]… [--label "…"] [--dry-run] |
One element's properties or label changed in its .arche file, by its id as archec export gives it (REQ-BRK-3, Vehicle.ctrl, BRAKE_STATUS). The value is written as arche-lang (--set period 20ms, --set satisfies REQ-1). Written only when the model has no more errors than before. What the Python package's Element.set runs. |
archec convert-handlers <main.arche> --to typescript|python|arche [--component X] [--dry-run] |
The model's handlers rewritten in another language, in place: the blocks (their fence and indentation kept), the `code` files (`code "x.py"` becomes `"x.ts"`, a new file beside the old one, which is kept; to `arche`, each function a ````arche block on its element), the transitions' guards, and the project's `handlers` (the component's, with `--component`). From ```arche ```` it is exact; from Python and TypeScript statement by statement, through what the action language says (handlers.md). A statement that does not translate stays as a // TODO(convert): <original> comment (# in Python), listed with why ([convert-todo]) and reported by archec check until it is written. A message's fields: bare names in Python, msg.field in TypeScript (message ↔ msg.name). Nothing is written when the result has more errors than the model; --dry-run says what would be. |
archec stubs <main.arche> [--out <dir>] [--beside] [-o arche.d.ts|arche.py] |
What editors need to know Arche's API and the model's names, in .arche/typings in the main file's folder: a typed arche package for the model's .py files (arche/__init__.pyi, arche/_model.pyi) and arche.d.ts for its .ts files. Nothing is written beside the code. A main file not called main.arche has .arche/typings/<name>. The folder has its own .gitignore. --out <dir> writes in another folder. --beside writes one arche.py and one arche.d.ts (with a tsconfig.json when there is none) beside the code files, as earlier versions did. For pyright on the command line: extraPaths = [".arche/typings"] under [tool.pyright] in pyproject.toml; for mypy: mypy_path = ".arche/typings" (python.md, handlers.md, editor.md). |
archec patterns [-o patterns.md] |
The reference of every declaration (patterns.md). |
archec ast <file.arche> |
The syntax tree (debugging). |
Code scanning (SARIF)#
--sarif report.sarif writes the diagnostics as SARIF 2.1.0,
which GitHub code scanning, GitLab and the SARIF viewers read. Each diagnostic code is a rule: its id is the
code (unresolved), its help is what archec explain <code> prints. Each diagnostic is a result at its
file, line and column, the file relative to the current folder: run archec from the repository's root.
The levels: error → error, warning → warning, info → note, hint → none.
A GitHub Actions job that shows them on the pull request:
name: model
on: [push, pull_request]
permissions:
contents: read
security-events: write # to upload the report
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npm install -g arche-lang
- run: archec check main.arche --sarif archec.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always() # upload even when archec check fails
with:
sarif_file: archec.sarif
category: archec
More on these commands#
archec review main.arche asks Claude whether each trace is plausible from what its two ends say, and
lists the doubtful ones (--suggest: the missing ones too). It is advice, never part of check or ci,
and it sends the traced elements' texts to the Anthropic API; --dry-run shows what and sends nothing.
For AI agents, archec mcp is the compiler as a Model Context Protocol
server on stdio. Its tools are the commands: check, explain, describe (the syntax of a keyword),
outline, brief (call it before changing a part), analyze, format, diff, generate, build. The agent edits the .arche files and calls
check. In Claude Code: claude mcp add archec -- archec mcp.