Start
The commands that start a project and give help.
Commands: archec new · archec help · archec config
| Command | What it does |
|---|---|
archec help [--all | <command>] |
The everyday commands; --all every command by what it is for; a command's usage, options and an example (as archec <command> --help). |
archec config [show [main.arche]] | ai offline|local-ai|online | allow <service> [url] | deny <service> [url] | remove <service> [url] | local-ai <url> [model] | services | test <service> [url] |
What may leave this machine (ai-engineering.md). Nothing, by default: ai online lets review, live-fix and new --describe send to Claude, ai local-ai to a model on this machine (local-ai http://localhost:11434 qwen3-coder); allow store https://store.arche-lang.xyz (or polarion, parts, issues, libraries, sigstore, github) lets that service out. Written in ~/.arche/config.json; the organisation policy (ARCHE_POLICY, /etc/arche/policy) and the project (ai, allow, deny, private) can only restrict it, and CI does not read it. show prints the mode in effect and where each setting comes from; test says whether a call would go out. Any command takes --offline, --ai <mode>, --allow service[=url] and --show-sent; each call is logged in .arche/egress.log. |
archec new [dir] [--template <id|owner/name>] [--board <id>] [--name <name>] [--parts "a -> b, b -> c"] [--target none|c|embassy|go] [--handlers typescript|python|arche] [--yes] [--dry-run] |
A new project that checks clean, instead of a blank page (new.md). From a template archec ships — blank (the default), rover-esp32, can-sensor-node (STM32G4 and CAN), drone-fc (a flight controller) — or one of the store (owner/name). --board puts a board of the board store in (or swaps the template's for it), --parts adds parts and links (lidar -> planner; a name alone is a part), --target writes a deployment for archec gen when there is none (go sets language go). The project says handlers typescript (its behaviour in TypeScript, handlers.md) unless --handlers says another, or the code it starts from is Python; the template's ```arche bodies translate to it. Each step is checked as archec check does, and one that would add an error is left out with a note. Writes main.arche, README.md and .gitignore. In a terminal it asks its questions (what you build, the board, the parts, the code), each one a flag did not answer; --yes takes the defaults; --dry-run prints the files and writes nothing. |
archec new <dir> --kind firmware|service|containers|ros2|desktop|library|robot [--target c|embassy|go] [--no-run] |
A project of a kind that already runs (new.md): the kind's template, its deployment, its code generated (the code you fill in into src/, committed, its USER CODE regions kept; the rest into generated/, ignored), a first test for each part no test plan names, CI files at the root (.github/workflows/archec.yml, .gitlab-ci.yml: archec ci, then the code generated, built and tested), .vscode/ (recommended extensions, tasks build, test and live), a README with the commands. Then the first run: archec check, archec test, archec gen, the kind's build and tests, each step said and one line at the end (first run: simulated 500 ms, built (make), 4/4 tests pass). A tool not on this computer, or a daemon not running, skips its step with a note; a step that fails exits 1. --no-run skips the first run; --dry-run writes nothing and runs nothing. Without --kind and in a terminal, the first question is the kind. |
archec new <dir> --kind robot --describe "unscrew a bottle cap" |
A small arm and a task in MuJoCo (robot-prototyping.md): the sentence picks the scene, robot-draw, robot-cap or robot-cube (and robot-draw's shape and size). Offline, its words do; with an AI allowed (ai local-ai, online), the model answers a scene, a shape and a size, checked, through the gateway, and an answer that is not one falls back to the words. The planner goes on a Raspberry Pi Pico; its C builds and runs here; with MuJoCo's Python the test plan runs against the arm. |
archec new --first-run [dir] |
The first run again, in a project archec new --kind made (its .archec/kind.json says the kind): check, simulate, generate, build, test. Exit 1 when a step fails. |
archec new <dir> --from <owner/name[@range]> [--store <where>] |
Remix: any store package (an architecture, a template, a board…) copied into a new project as an editable copy, not a uses dependency, checked as archec add checks it (hash, signature, trust). The project gets derived-from "owner/name@version"; what the package uses from the store is taken with archec add. A package without a main file gets one that includes its files. |
archec new <dir> --describe "a robot with 2 motors, a lidar and a Raspberry Pi" [--kind <id>] [--board <id>] [--rounds 4] [--model id] [--dry-run] |
Claude (claude-opus-5-5) writes the first model from a sentence: it gets a compact language reference, the board store's boards and a template as an example; what comes back is checked as archec check does, and the errors go back to it, up to --rounds times. A first draft to read, not a verdict. It sends text out: your description, and archec check's messages on what Claude wrote, go to the Anthropic API, only when this command runs; --dry-run prints the prompt and sends nothing. Credentials: ANTHROPIC_API_KEY. The kind is --kind, else the one the words of the sentence name (firmware, esp32, stm32…: each kind's words); --dry-run says which. Offline by default: archec config ai online (or ai local-ai, a model on this machine) lets it send (ai-engineering.md). |