archec commands

archec <command> … — archec with no command lists the everyday ones; archec help --all lists every command by what it is for (the sections below), archec help <command> (or archec <command> --help) gives one command's usage and an example; archec --version gives the version. A command that checks something exits 1 when it finds a problem, so each one can be a CI step; archec ci is all of them at once.

Start#

Write and check#

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

Build and test#

Analyse#

Present#

Requirements#

Generate#

Import#

Refactor#

Rewrites that keep the project the same: each one writes nothing unless the project builds the same. The old names (archec move-traces, archec name-components, archec translations, archec extract-component) still run, with a note.

Code and model#

Libraries#

Boards#

Known boards — the store archec ships (arche-hw-store: ESP32, STM32 Nucleo, Raspberry Pi Pico and Pi, nRF52840 DK, Jetson Orin Nano, Kria KR260) and your own collections, found in the project's libraries, in ARCHE_BOARDS (a path list; VS Code's arche.boardCollections sets it) and beside archec. A board is a component of kind board: its product { vendor; part-number; url }, its processors (compute { hal …; chip "…" }) and its connectors with their pins (pins { tx PA12; rx PA11 }). A binary on a board runs on its processor, and archec gen --target embassy drives the CAN controller on the board's pins. See the board store.

Store#

The Arche Store: architectures, drivers, specifications and boards people share, as signed packages. Which store: --store <where> (a folder, a git URL, or a hosted store's https URL), else ARCHE_STORE, else what archec store use set. See the Arche Store.

Provenance#

Who wrote the code: the model, an AI assistant, or a person. Each line of a code file gets one of four origins:

• generated: archec gen wrote it, and it is still what gen wrote. Gen leaves .archegen.json in its output folder: the files it wrote, with a fingerprint per line. A file with no manifest but a Generated by archec line at the top counts as generated whole.
• AI: an AI assistant wrote it. The commit that last changed the line says so: a Co-Authored-By: trailer naming an assistant (Claude, Copilot, Codex, Cursor, Gemini, Aider, Devin…), Generated-by: (not archec), Assisted-by:, AI-assisted: yes, or an assistant's address as author. Or a marker in .arche/provenance.jsonl says so.
• edited after gen: gen wrote the file, and a person changed this line since.
• human: the rest.

The lines come from git blame, so each line counts for the commit that last changed it. Outside a git repository, the markers and the gen manifests are all there is.

The Claude Code hook#

Add this to .claude/settings.json in the project. After each edit, it notes the lines Claude wrote in .arche/provenance.jsonl:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [{ "type": "command", "command": "archec provenance hook" }]
      }
    ]
  }
}

Without archec on the PATH, copy tools/provenance/claude-hook.mjs into .claude/hooks/ and use "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/claude-hook.mjs". It needs only node. ARCHE_AI_TOOL and ARCHE_AI_MODEL set the tool and model it records.

Commit .arche/provenance.jsonl with the code, so others see the same. A line of it:

{"file":"src/plan.c","lines":[4,6],"hashes":["a1b2c3d4","…"],"tool":"claude-code","session":"…","time":"2026-11-10T12:00:00Z"}

hashes are the first 8 hex digits of the SHA-1 of each line written, trimmed. A marker counts for a line only when the line has the same text and was not committed before the marker's time.

Examples#

npm install && npm run build
node dist/cli.js build examples/autonomous-car/main.arche -o out   # → an Arche project
../arche/dist/arche-darwin-arm64 --project out                     # open it
node dist/cli.js check examples/autonomous-car/main.arche          # lint (exit 1 on errors, --strict on warnings, --json)
node dist/cli.js fmt --write examples/**/*.arche                   # format
node dist/cli.js fmt --simplify --write old.arche                  # rewrite in the short forms (same meaning)
node dist/cli.js fmt --extract-code --write main.arche             # move ```python blocks into .py files (same meaning)
node dist/cli.js stubs main.arche                                  # arche.py: Arche's helpers + the model's names, for Python tooling
node dist/cli.js pull main.arche --write                           # code edited in the Arche app → back into the .py / .arche sources
node dist/cli.js test main.arche                                   # build + arche-cli test, errors shown at their source line
node dist/cli.js analyze examples/autonomous-car/main.arche        # core load, response times, bus load, latency chains
node dist/cli.js difftest examples/live/main.arche                # the simulator and the generated C on the same random inputs
node dist/cli.js physics examples/dc-motor/main.arche Drive --integrator implicit --tol 1e-6  # a physical network, a stiff one too
node dist/cli.js physics examples/dc-motor/main.arche Drive --linearize --inputs supply.v --lqr 1,0.1  # A, B, C, D, its modes, an LQR gain
node dist/cli.js physics examples/dc-motor/main.arche Drive --batch 100 --vary motor.r=0.8..1.2 --csv runs.csv  # 100 runs over worker threads
node dist/cli.js sim examples/live/main.arche --html sim.html     # one page that runs the model live: pause, step, speed, send, plots
node dist/cli.js doc examples/autonomous-car/main.arche -o spec.tex # LaTeX specification (lualatex spec.tex)
node dist/cli.js doc examples/autonomous-car/main.arche --template examples/templates/autonomous-car-spec.docx -o spec.docx # your Word template, filled ({{ … }}: docs/templates.md)
node dist/cli.js diagram main.arche Car --md >> README.md          # a diagram as Mermaid, which GitHub draws (or --format d2|svg)
node dist/cli.js validate ../arche/sample-aesa                     # schema-check any Arche project
node dist/cli.js patterns                                          # the pattern reference
node dist/cli.js import model.sysml -o model.arche                 # a SysML v2 model in arche-lang
node dist/cli.js import bus.dbc -o bus.arche                       # a CAN DBC: frames, signals, nodes, routes
node dist/cli.js capella main.arche -o project.zip                 # a Capella 6.1 project (and back: capella model.capella -o dir)
node dist/cli.js ci main.arche --junit report.xml                   # every check a pipeline runs, one exit code
node dist/cli.js check main.arche --sarif archec.sarif             # the diagnostics as SARIF, for code scanning
node dist/cli.js lib main.arche lock                               # the versioned libraries used, locked in arche.lock
node dist/cli.js recover src -o recovered.arche                    # the architecture of code, as arche-lang
node dist/cli.js conform recovered.arche                           # the code's imports against the model's links
node dist/cli.js arch-diff src main..HEAD --md                     # what a branch changed in the architecture

More on some 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.

While a system runs, archec live shows which requirements, chains, threads and containers pass or fail; archec live-fix REQ-1 asks Claude why one fails — from the evidence, the measured and predicted timings and the declarations involved — and proposes edits to the .arche files, each checked against the text at its line. In VS Code, "Arche: Start Live" colours those lines, and "Explain & fix with Claude" previews the edits. --dry-run shows what would be sent.

Sign-off is kept in the repository: archec approve REQ-1 Car.brakes --as "A. Martin" --role safety writes one line per approval to reviews/approvals.yaml — the element, a fingerprint of what it says, who, when. When the element changes, its approval is stale (archec approvals --stale); archec cert shows who approved each requirement, and archec ci --require-approval fails while one is missing. archec baseline --sign signs a baseline with an SSH key (ssh-keygen -Y sign, as git does), checked by archec baseline --verify against reviews/allowed_signers.

archec issues sync opens an issue in Jira, GitHub or GitLab for each failing case and each unverified requirement, and writes its key on the element (issue "CAR-128"); the next run updates it, or comments and closes it once the problem is gone. The tracker is named in issues.yaml, the token comes from the environment, and --dry-run prints the requests without sending them.

archec parts looks the bill of materials' part numbers up at Nexar (Octopart), DigiKey or Mouser — stock, price breaks, lifecycle — and keeps the answers with their date in .arche/parts-cache.json; archec check then warns about a part at its end of life, not recommended for new designs or out of stock, from that cache alone.

archec diagram main.arche <view> writes any diagram the editor shows — a system, a component, a state machine, a scenario, a view — as Mermaid (--md fences it, for a README or a pull request, where GitHub draws it), D2, or SVG laid out by ELK. A viewpoint with include/exclude lines is a view of its own, a query over the model (include * -> adcu, exclude kind sensor): the diagram stays right as the model changes, and a term that matches nothing is a warning. --all -o docs/diagrams writes them all. archec diagram main.arche emergency-stop --format svg --play plays a scenario on its system's blocks, step by step, as an SVG with no script; archec doc --html puts every view and played scenario in the page.

archec sim main.arche --html sim.html writes one page that runs the model in any browser, live, as MuJoCo's viewer runs a scene: play and pause, a step to the next event or by a fixed time, a speed from 0.1× to 10×, a scrubber back over what has run (the run replayed, with what you sent), a form per input port that sends one of its messages now (its fields with their type, range and enum values), a push — a step or a pulse — on a physical network's sources, and live plots of the states, variables, message fields and physical quantities chosen. The keys are listed on the page (docs/sim.md).

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, analyze, format, diff, generate, build. The agent edits the .arche files and calls check. In Claude Code: claude mcp add archec -- archec mcp.

Python#

lib/python/archelang reads a model in a script or a notebook, through archec export --json (standard library only; pandas for the tables, when installed):

import archelang                                   # pip install -e lib/python, or PYTHONPATH=lib/python
m = archelang.load("examples/autonomous-car/main.arche")
m.requirements.unverified()                        # [<requirement REQ-SAF-001 …>, …]
m["REQ-BRK-001"].satisfied_by                      # [<component Adcu …>]
m["Car.brakes"].ports                              # a part's ports, its definition's
m.find(kind="port", direction="in")
m["REACTION_TIME"].value                           # Quantity(value=150, unit='ms')
m.requirements.to_dataframe()                      # with pandas
m["REQ-BRK-001"].set("priority", "high")           # archec edit: written only if it adds no error

Each element has its id, kind, label, file and line, parent and children, properties (el.period, el.prop("stale-after")), and its traces (satisfies, verified_by, derives…). Links and transitions have their source, target, and the parts they are on. archelang finds archec on the PATH, or ARCHEC names it. examples/brake-by-wire/model.ipynb is a short notebook.

SysML v2 API#

archec api serve main.arche serves the model over the OMG Systems Modeling API (the SysML v2 REST API), read-only: the project, its commits — git's history of the model's folder, and the files as they are — its baselines as tags, the elements at each commit, their relationships, and queries.

archec api serve examples/autonomous-car/main.arche --port 9000
curl -s localhost:9000/projects
curl -s -X POST localhost:9000/projects/<id>/query-results \
  -d '{"@type":"Query","where":{"@type":"PrimitiveConstraint","property":"@type","operator":"=","value":"RequirementUsage"}}'