Build and test
The commands that build the Arche project, run its tests and simulate it.
Commands: archec build · archec pull · archec test · archec sim · archec physics · archec fit · archec difftest · archec where · archec ci · archec validate · archec diff
On this page: More on these commands
| Command | What it does |
|---|---|
archec build <main.arche> [-o <dir>] [--force] |
The Arche project folder (default ./arche-out); open it with arche --project <dir>. Refuses to overwrite code edited in Arche and not pulled back. |
archec pull <main.arche> [-o <dir>] [--write] |
Code edited in the Arche app, back into the .py defs and code blocks it came from (a dry run without --write). |
archec test <main.arche> [-o <dir>] [--plan <id>]… [--case <PLAN/CASE>]… [--coverage] [--allow <file>] [--sim web|python] [--python <exe>] [--no-python] [--ui-golden [--tolerance 0.1]] [--timeout 600] |
Build, then run the test plans in the Arche simulator (arche-cli): each case, the requirements it verifies, and with --coverage the states, transitions, messages and functions the run went through. --allow: the known failures, one PLAN/CASE per line. A case with a ui step (do press hmi.engage, expect hmi.mode.text == "…": ui) runs on the browser simulator — Arche's has no ui — in the same report, and needs no arche-cli; --sim web runs every case there, --sim python none. There, Python the action language can't say runs in python3 (--python <exe> names it); with --no-python, or no python3, a case that reaches it is inconclusive: neither passed nor failed, and the run exits 1 (sim). --ui-golden: then each screen compared with its golden, as archec ui snapshot. Each case that ran is recorded as evidence for archec status, with where it ran and the fingerprints of what it depended on (.arche/evidence/test.jsonl; --no-record: not). |
archec test <main.arche> --ladder [--plan <id>]… [--case <PLAN/CASE>]… [--board <probe>] [--hook <script>] [--deployment D] [--sim python] [-o <dir>] [--json] [--verbose] [--timeout 3600] |
The test ladder: the cases on the simulator, then the firmware in Renode, then on the board, stopping at the first rung that fails; one line per rung. The two upper rungs are the project's hook (board.sh beside the model, --hook, or ARCHE_LADDER_HOOK): hook --renode when the deployment has a binary on a board and renode is installed, hook only with --board <probe> (it flashes) and a flash tool of the chip installed. A missing tool or hook is a rung skipped, with the reason, not failed; a hook that exits 2 is skipped too. Each rung's output is in <out>/.archec/ladder/, the ladder in <out>/.archec/ladder.json (--json: printed). What the rungs record says where it ran: archec status shows the highest rung each requirement reached. Exit 1 when a rung fails. |
archec test <main.arche> --target vhdl [--plan <id>]… [--case <PLAN/CASE>]… [-o <dir>] [--deployment D] [--json] [--verbose] [--timeout 600] |
The test cases on an FPGA's VHDL: the VHDL and a testbench per case written under <dir>/vhdl, analysed and run in GHDL. Each case that ran is evidence at the place ghdl, and leaves a trace in <dir>/vhdl/trace/ for archec why, why-not and timing. Exit 0: every case passed; 1: one failed; 2: it could not run (no GHDL here: nothing is downloaded, the message says where it comes from). Extension: fpga. |
archec test <main.arche> --against <git-ref> [--plan <id>]… [--case <PLAN/CASE>]… [--sim python] [-o <dir>] [--json] |
A test that proves a fix: the cases (with none named, those new or changed since the ref) on a checkout of the ref — a git worktree in a temporary folder, the cases as they are now added to the model as it was — then on the working tree, on the simulator. A case that fails there and passes here proves the fix (a fix record for archec status); one that passes on both does not catch the bug. Exit 0 only when every case proves the fix; 2 when the two builds cannot be compared (no repository, no such ref, a case the older model does not take). |
archec run <main.arche> [-o <dir>] |
Build and run the simulation; each Python error is shown at its line in your sources. |
archec sim <main.arche> [--for 10s] [--system S] [--deployment D] [--seed 1] [--keyframe K] [--json] [--html out.html] [--plant plant_bridge.py [--test [TP|TC]]] [--python <exe>] [--no-python] [--py-timeout 5s]archec sim <main.arche> --doctest [--json] [--python <exe>]archec sim <main.arche> --batch N [--seed 1] [--vary part.var=lo..hi]… [--threads k] [--print a,b] [--csv file] [--json] |
Run the model's behaviour with nothing installed — no Arche, and no Python unless a body is Python the action language cannot say: state machines (on a message, on "after 500ms"), deadlines and watchdogs, ```arche bodies and the Python the action language can say, ports and links, a deployment's periodic threads, on a virtual clock. Prints the trace (each message with its from and to port and its payload, each state change); --json the same as JSON. --html: one self-contained page that runs it live in a browser — the block diagram, each message a dot along its link, each part's state in its box; Play/Pause, Step (the next event) and Step by (a fixed time), a speed from 0.1× to 10×, a time scrubber back over what has run, Reset; a form per input port that sends one of its messages now, a push (step or pulse) on a physical network's sources (the network integrated in the page), live plots of states, variables, message fields and physical quantities; keys (space, →, Shift+→, ←, + / −, Home, R) listed on the page. What it does not simulate is said, never guessed: the bodies in Python the action language can't say are listed once at the start, run in python3 (--python <exe>), or not simulated with --no-python or no python3. --plant: against a plant run elsewhere, in lockstep — mujoco/plant_bridge.py of archec gen --target mujoco (run with MUJOCO_PYTHON, else python3), or any command that speaks its JSON lines: every period the plant says, its sensors' messages come in as if their parts sent them, the model runs a period, and what it sent to the plant's parts goes back. A sensor's noise, resolution and range, an actuator's ctrl range, gain, lag and force-range and a port's latency are simulated (the trace shows each command an actuator takes and its output then), the noise drawn from --seed (simulation { seed }, else 1); --keyframe K starts from that keyframe of the system (and the plant from it). Python the action language cannot say runs in one python3 for the run (--python, ARCHE_PYTHON, the model's .venv, else python3), each call synchronous, seeded, on the simulated clock, with a timeout (--py-timeout, 5 s); its packages (pip "numpy") are checked and the pip command printed, nothing installed. --doctest: the doctests of every .py file the model names, in that Python. See the browser simulator and Python bodies. --batch N: N runs over worker threads, a part's variable that is a number drawn within each --vary range (its first value); for each run the messages, state changes and errors counted and every part's variables that are numbers at the end (--print keeps some), then their mean, min, max and σ — the same runs for a seed on any number of threads. |
archec physics <main.arche> <System|Def> [--for 1s] [--step 1ms] [--every 100ms] [--integrator rk4|euler|implicit|trapezoid] [--tol 1e-6] [--print a,b] [--csv file] [--json] [--set name=value] [--keyframe K] [--seed 1] [--equations]archec physics <main.arche> <System> --linearize [--at start|2s|x=1,…] [--inputs a,b] [--outputs y,z] [--lqr Q,R] [--json]archec physics <main.arche> <System> --batch N [--seed 1] [--vary name=lo..hi]… [--threads k] [--print a,b] [--csv file] [--json] |
A physical network run with nothing installed: parts whose ports have a potential and a flow (include "std/physics"), linked with no direction. Flattened (potentials equal and flows adding up to zero at each node), checked (as many equations as unknowns, each unknown given once — else the parts concerned are named), sorted into blocks, each solved in order — a linear loop once, a nonlinear one torn and solved by Newton's method on its tear variables — and the states integrated at a fixed step (RK4, --euler). --integrator implicit (backward Euler) and --integrator trapezoid (second order) solve each step by Newton's method, the Jacobian by finite differences: on a stiff network (a fast time constant beside a slow one) they keep a step RK4 blows up at. --tol makes the step adapt, the error on each step within it (relative and absolute): Dormand–Prince 5(4) for RK4, step doubling for the others; the number of steps is printed on stderr. Prints --print's variables (default: the states) every --every (a tenth of the run); --csv writes every variable at every step; --set gives an input (an in signal linked to nothing) or a part's parameter (motor.ra.r=2) its value; --equations prints the sorted equations and does not run. Index-0 only: states tied by an equation are reported, not reduced. --linearize: the network around an operating point, dx/dt = A·x + B·u, y = C·x + D·u, by central finite differences of the states' rates (as MuJoCo's mjd_transitionFD), to 7 digits. The point is the start (--at start), where a run leaves it (--at 2s), or states given (--at c.v=5). The inputs are the network's, or parameters of the parts whose equations use them (--inputs supply.v: a composite's parameter is passed on, so name the part that uses it); the outputs any of its variables (default: the states). Then the eigenvalues of A — each a time constant, or a pair's frequency and damping — and whether it is stable, marginally (an integrator: a position, an angle) or not. --lqr Q,R: the gain K of u = -K·(x - x0) that minimizes ∫ xᵀQx + uᵀRu, Q and R diagonal (one weight for all, or one each: 10:1:1,0.1), by the continuous Riccati equation, and the modes of the closed loop. --batch N: N runs, each with the parameters (motor.r) or inputs --vary names drawn within their range, spread over worker threads (--threads, by default as many as there are cores, 8 at most); each run's --print variables (default: the states) at the end, then their mean, min, max and σ. Run i draws from the seed and i alone, so a seed gives the same runs on any number of threads. --csv: one row a run; --json: the runs and the summary. An actuator's in signal with a gain, lag or force-range (or a type with a range) takes its command at <port>.command and acts through them, the lag a state of the network; a sensor's out signal is printed as it reads (its noise from --seed, its type's range, its resolution, its latency). --keyframe K starts from a keyframe of the system (its states, its actuators' commands); --linearize --at K linearizes there. |
archec fit <main.arche> <System|Def> <data.csv|log>… --params a,b[=lo..hi] [--signals x[=series],…] [--inputs u=series] [--step 1ms] [--method lm|nelder-mead] [--json] [--html report.html] [--write]archec fit <main.arche> --pass [TP|TC] [--params A,B=lo..hi] [--plant plant_bridge.py] [--method coordinate|grid|nelder-mead] [--tries 40] [--seed 1] [--propose ai] [--task "…"] [--write] [--no-tries] [--json] |
A physical network's parameters from what was measured (system identification). The data: a CSV (a header row, the time first or in a column t, a signal in each other column, a unit in brackets converted to SI: t (ms), w (rpm); an empty cell is no sample), or a log archec replay reads (candump, ASC, BLF, MCAP, JSON lines), decoded by the model, each numeric field a series MSG.field. A series drives the input (an in signal linked to nothing) or is compared with the variable it is named as: load.w, its flat name load_w, or MSG.load_w; --signals load.w=MOTOR.speed and --inputs src.u=PROBE.u say it when the names differ. A parameter is a part's (motor.r: its argument, else its definition's default), the system's own, or a parameter declaration; its bounds are its tolerance (or min/max), else its sign, or name=lo..hi in its unit. The network is run (RK4, the measured inputs linear between samples) from the model's start values, and the parameters found by least squares — each signal scaled by its spread — by Levenberg–Marquardt on a finite-difference Jacobian, Nelder–Mead when that makes no progress (or --method nelder-mead). Prints each value in its unit with its uncertainty (1σ, from s²·(JᵀJ)⁻¹), the RMS error of each signal before and after. Warns fit-no-influence for a parameter the signals do not change (not fitted) and fit-correlated for two that change them the same way (correlation above 0.999). --html draws measured, before and after per signal; --write puts the fitted values in the source (a part's argument replaced or added, a default or a parameter's value), checked first as archec edit does. --pass: a controller's tunable constants (a const with a range, or named --params KP=5..80) tried until every test case and every requirement checked on the run passes, on the simulator or against --plant (tuning). The search is seeded and bounded by --tries: coordinate steps by default, a grid, or Nelder–Mead, each failed comparison scored by how far off it was. --propose ai lets an AI propose the values, through the gateway (offline: refused); the run still decides. Each try goes in .arche/tries/ (values, verdicts, a sampled trace), --no-tries keeps none. --write writes the passing values, an AI's marked in .arche/provenance.jsonl. Exit 1 when no try passes. |
archec difftest <main.arche> [System] [--seed 1] [--steps 50] [--for 2s] [--target c] [--deployment D] [-o dir] [--json] |
Differential testing: the simulator (archec sim's runtime) and the code archec gen --target c writes, driven with the same inputs, must do the same thing. The inputs are random but repeatable (--seed): --steps messages from outside, each to a port of a part that receives it, with random field values, 1 to 20 ms apart. The C of each component is built with a harness (CC, else gcc, else cc) that plays them on a virtual clock, sends along the system's links with their latency, and does what happens at one instant in the simulator's order. Then the two traces — inputs, state changes, messages sent with their payloads (the C one decoded from its bytes), messages sent on a port linked to nothing — are compared in order and in time, and the first divergence is printed with the events before it. What one side cannot translate (Python the action language cannot say, TypeScript outside the portable subset, a body that waits) is listed as not compared. -o: where the C and its harness go (a temporary folder by default); --json: the inputs, both traces and the divergence. Exit 1 on a divergence, 2 when it cannot run (no compiler, the C does not build). A sensor's noise is drawn from the same seed on both sides (the C built with -DARCHE_SIM), and each command an actuator takes, with its output then (gain, lag, force-range), is compared too. |
archec where <main.arche> [-o <dir>] "<error text>" |
Where an error Arche reports is in the sources: (Controller › Control loop, line 4) → ctrl.py:32. |
archec where <main.arche> [--gen generated] [--from <dir>] "<compiler output>" | - |
A C, Rust or Go compiler's error (gcc, clang, rustc, go) in code archec gen wrote → the model element it comes from and its .arche line, through generated/.archec/genmap.json; a line in a USER CODE region says so. --from: the folder the compiler ran in (make in c/<binary>). With -, the output read from stdin, the element under each line (regeneration). |
archec ci <main.arche> [-o <dir>] [--strict] [--coverage-min <percent>] [--require-tests] [--require-approval] [--debt-max <percent>] [--tests-first [--range a..b] [--prove-red] [--test-cmd "… {file}"]] [--junit <report.xml>] [--sarif <report.sarif>] |
What a pipeline checks, in one command: lint, format, ui (a binding, a press or a ui test step that does not hold — a button sending a message renamed since), timing, TARA, build, tests and coverage. One line per gate, a JUnit report with --junit, every diagnostic (style findings too) as SARIF with --sarif, exit 1 when a gate fails. Without arche-cli the cases with a ui step still run (on the browser simulator), the others are skipped, unless --require-tests. --require-approval: an approval gate, every requirement approved at what it says now (archec approve). --tests-first: a tests-first gate over --range (by default, from where the branch left its upstream, origin/main, main or master). Each function the range adds, outside test files, needs a requirement (on its fn or its part) and a test case that verifies it, in the model and in git at the function's commit or before. A case's file is its source, or its label when that is a path ("test/add.test.js", "test/gen.test.js › embassy"). --prove-red runs each such test on the commit before the function's, in a temporary git worktree removed after, with the test file as it was at the function's commit; it must fail there. The command is by the file's language (node --test, pytest, go test, cargo test), or --test-cmd with {file} and {name}. Functions written by an AI assistant with no requirement or no test are said apart. The agent-context gate fails when CLAUDE.md or AGENTS.md beside the model holds a block of archec agent-context the model no longer gives (no such gate without one). |
archec validate <arche-project-dir> |
An Arche project's YAML against the schema. |
archec diff <a> <b> |
Two projects (folders, or a .arche entry) compared as data. |
More on these commands#
archec sim main.arche --html sim.html writes one page that runs the model live in any browser, the way
MuJoCo's viewer runs a scene. The page has:
- play and pause, a step to the next event or by a fixed time, and 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, with each field's type, range and enum values;
- a push (a step or a pulse) on a physical network's sources;
- live plots of the states, variables, message fields and physical quantities you choose.
The keys are listed on the page (docs/sim.md).