axiometa-cli 1.0.3__tar.gz → 2.0.0__tar.gz

axiometa_cli-2.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: axiometa-cli
+Version: 2.0.0
+Summary: Axiometa hardware truths and upload methods, for your editor and your AI.
+Author-email: Axiometa <dr.dumcius@gmail.com>
+Project-URL: Homepage, https://axiometa.io
+Project-URL: Source, https://github.com/axiometa/axiometa-studio/tree/main/axiometa-cli
+Project-URL: Studio, https://studio.axiometa.io
+Keywords: hardware,ai,mcp,esp32,nrf52840,arduino,iot,cli,maker,embedded
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pyserial>=3.5
+
+# axiometa-cli
+
+**Hardware truths and upload methods, for a repo that is not ours.**
+
+You are deep in an existing project and adding Axiometa hardware to it. Your editor is your editor,
+your AI is your AI, your files are yours. This provides the two things neither of them can derive:
+what the board actually is, and how to get firmware onto it.
+
+It creates nothing in your repo — no manifest, no config file, no convention about where a sketch
+lives. Every command is stateless.
+
+```bash
+pip install axiometa-cli
+axiometa login <key>                                 # from Studio -> account menu -> Headless
+axiometa provision                                   # once per machine
+axiometa board genesis-one                           # pins, buses, fqbn, silicon gotchas
+axiometa part  genesis-one AX22-0005                 # one part's pins, library, init, rules
+axiometa upload ./firmware -b genesis-one --parts AX22-0005
+```
+
+## Hardware truths
+
+An Axiometa board is a custom board package. Its pins, its `esp32:esp32:axiometa_*` target and its
+parts match nothing in a stock core, so none of it is inferable — and a wrong pin map compiles
+cleanly and fails silently in hardware.
+
+| | |
+|---|---|
+| `boards` | what exists, and what language each speaks |
+| `board <id>` | ports and pin naming, shared vs unique buses, which pins read analog, fqbn, build options, silicon gotchas |
+| `parts <id>` | the catalog: every module, display, onboard radio, host part |
+| `part <id> <part>` | one part's real pins, i2c address, library name+version, locked init, coding rules |
+
+Add `--json` to any of them. That is the form an agent wants.
+
+## Upload methods
+
+| | |
+|---|---|
+| `provision` | install the private toolchain |
+| `devices` | what is plugged in |
+| `compile <dir> -b <board>` | build with the right target, profile and libraries |
+| `upload <dir> -b <board>` | build and put it on the board |
+
+`--parts AX22-0005,AX22-0031` names what the build uses, which decides the libraries. You name them
+because there is no manifest to read them from, and guessing from `#include`s is how a build ends up
+with the wrong library. `--option PartitionScheme=app_max_no_ota` sets a build option.
+
+## MCP
+
+```bash
+axiometa mcp
+```
+
+The same tools over stdio, for clients that speak MCP. Six: `list_boards`, `get_board`, `list_parts`,
+`get_part`, `compile`, `upload`. File editing and shell are the client's own job, so they are not here.
+
+It holds no prompt and does no reasoning. Your AI writes the code.
+
+## It cannot collide with your Arduino setup
+
+Axiometa boards are a custom board package laid into a **pinned** ESP32 core (3.3.6 — 3.3.7/3.3.8
+carry a NimBLE regression that boot-loops Matter sketches on ESP32-S3). Installing that into a shared
+arduino-cli would rewrite `boards.txt`, replace your core version, and add libraries to your
+sketchbook.
+
+So we never touch yours. Everything lives in one prefix:
+
+```
+~/.axiometa/toolchain/
+  bin/arduino-cli          our own pinned binary — never the one on your PATH
+  arduino-cli.yaml         our own config, passed as --config-file on every invocation
+  data/                    our cores + our patched boards.txt
+  user/libraries/          our libraries
+  venv/                    our mpremote / adafruit-nrfutil
+```
+
+Your `arduino-cli`, your core version, your `arduino-cli.yaml`, your sketchbook and your Python
+environment are never read and never written. Uninstall is `rm -rf ~/.axiometa`.
+`AXIOMETA_HOME` moves the prefix.
+
+## Where the knowledge comes from
+
+The CLI ships no board data. It fetches `GET /api/knowledge/boards` from its own service (`server/`,
+deployed separately) and caches it under `~/.cache/axiometa/`, re-fetching only when the content hash
+changes. A board or part added upstream reaches every installed CLI with no release.
+
+That fetch needs a **key**. Studio mints one per signed-in account (account menu -> Axiometa
+Headless); `axiometa login <key>` stores it, or set `AXIOMETA_KEY`.
+
+The token is HMAC-signed and carries a public `key_id`:
+
+```
+axm_<base64url(user_id:key_id:issued_at)>.<hmac-sha256>
+```
+
+Signature first, database second. The HMAC proves authenticity with no lookup, so a forgery is
+rejected before anything touches the database. The `key_id` is then what makes a single key
+revocable and what usage counts against — the two questions a signature cannot answer. The raw
+token is stored nowhere; it is shown once, at creation.
+
+Both deployments need the same `AXIOMETA_HEADLESS_SECRET`. Schema: `backend/sql/headless.sql`.
+Supabase is optional on the service — without it the signature still gates access and usage simply
+is not recorded, because a knowledge fetch must never fail over an analytics table. With no secret
+set at all the service stays open rather than locking everyone out over a missing env var.
+
+Board knowledge is authored once, in `backend/knowledge/`. `build_knowledge.py` is the only bridge:
+it copies the hardware payload here and **deletes** anything carrying a `%%TOKEN%%` — those are
+build-time substitutions belonging to a browser product this one is not part of. Deleted, not
+reworded: hardware knowledge is pins, buses, addresses, libraries, init and timing, and a placeholder
+for someone else's build step is none of those. Everything else passes through as written. Run
+`--check` in CI.
+
+## Boards
+
+| Board | Silicon | Upload |
+|---|---|---|
+| Genesis One / Genesis Mini | ESP32-S3 | `upload` |
+| XIAO Shield (ESP32-S3) | ESP32-S3 | `upload` |
+| XIAO Shield (nRF52840) | nRF52840 | `upload` (Seeed nRF52 core) |
+| Pi HAT | RP2040 | `upload` (mpremote over the Pi UART) |
+
+Verbs are facts of the (board, language), read from `board.json` — not a list in this README.
+
+Python 3.9+. `pyserial` is the only dependency; the build tools install into the private prefix.

axiometa_cli-2.0.0/README.md

@@ -0,0 +1,125 @@
+# axiometa-cli
+
+**Hardware truths and upload methods, for a repo that is not ours.**
+
+You are deep in an existing project and adding Axiometa hardware to it. Your editor is your editor,
+your AI is your AI, your files are yours. This provides the two things neither of them can derive:
+what the board actually is, and how to get firmware onto it.
+
+It creates nothing in your repo — no manifest, no config file, no convention about where a sketch
+lives. Every command is stateless.
+
+```bash
+pip install axiometa-cli
+axiometa login <key>                                 # from Studio -> account menu -> Headless
+axiometa provision                                   # once per machine
+axiometa board genesis-one                           # pins, buses, fqbn, silicon gotchas
+axiometa part  genesis-one AX22-0005                 # one part's pins, library, init, rules
+axiometa upload ./firmware -b genesis-one --parts AX22-0005
+```
+
+## Hardware truths
+
+An Axiometa board is a custom board package. Its pins, its `esp32:esp32:axiometa_*` target and its
+parts match nothing in a stock core, so none of it is inferable — and a wrong pin map compiles
+cleanly and fails silently in hardware.
+
+| | |
+|---|---|
+| `boards` | what exists, and what language each speaks |
+| `board <id>` | ports and pin naming, shared vs unique buses, which pins read analog, fqbn, build options, silicon gotchas |
+| `parts <id>` | the catalog: every module, display, onboard radio, host part |
+| `part <id> <part>` | one part's real pins, i2c address, library name+version, locked init, coding rules |
+
+Add `--json` to any of them. That is the form an agent wants.
+
+## Upload methods
+
+| | |
+|---|---|
+| `provision` | install the private toolchain |
+| `devices` | what is plugged in |
+| `compile <dir> -b <board>` | build with the right target, profile and libraries |
+| `upload <dir> -b <board>` | build and put it on the board |
+
+`--parts AX22-0005,AX22-0031` names what the build uses, which decides the libraries. You name them
+because there is no manifest to read them from, and guessing from `#include`s is how a build ends up
+with the wrong library. `--option PartitionScheme=app_max_no_ota` sets a build option.
+
+## MCP
+
+```bash
+axiometa mcp
+```
+
+The same tools over stdio, for clients that speak MCP. Six: `list_boards`, `get_board`, `list_parts`,
+`get_part`, `compile`, `upload`. File editing and shell are the client's own job, so they are not here.
+
+It holds no prompt and does no reasoning. Your AI writes the code.
+
+## It cannot collide with your Arduino setup
+
+Axiometa boards are a custom board package laid into a **pinned** ESP32 core (3.3.6 — 3.3.7/3.3.8
+carry a NimBLE regression that boot-loops Matter sketches on ESP32-S3). Installing that into a shared
+arduino-cli would rewrite `boards.txt`, replace your core version, and add libraries to your
+sketchbook.
+
+So we never touch yours. Everything lives in one prefix:
+
+```
+~/.axiometa/toolchain/
+  bin/arduino-cli          our own pinned binary — never the one on your PATH
+  arduino-cli.yaml         our own config, passed as --config-file on every invocation
+  data/                    our cores + our patched boards.txt
+  user/libraries/          our libraries
+  venv/                    our mpremote / adafruit-nrfutil
+```
+
+Your `arduino-cli`, your core version, your `arduino-cli.yaml`, your sketchbook and your Python
+environment are never read and never written. Uninstall is `rm -rf ~/.axiometa`.
+`AXIOMETA_HOME` moves the prefix.
+
+## Where the knowledge comes from
+
+The CLI ships no board data. It fetches `GET /api/knowledge/boards` from its own service (`server/`,
+deployed separately) and caches it under `~/.cache/axiometa/`, re-fetching only when the content hash
+changes. A board or part added upstream reaches every installed CLI with no release.
+
+That fetch needs a **key**. Studio mints one per signed-in account (account menu -> Axiometa
+Headless); `axiometa login <key>` stores it, or set `AXIOMETA_KEY`.
+
+The token is HMAC-signed and carries a public `key_id`:
+
+```
+axm_<base64url(user_id:key_id:issued_at)>.<hmac-sha256>
+```
+
+Signature first, database second. The HMAC proves authenticity with no lookup, so a forgery is
+rejected before anything touches the database. The `key_id` is then what makes a single key
+revocable and what usage counts against — the two questions a signature cannot answer. The raw
+token is stored nowhere; it is shown once, at creation.
+
+Both deployments need the same `AXIOMETA_HEADLESS_SECRET`. Schema: `backend/sql/headless.sql`.
+Supabase is optional on the service — without it the signature still gates access and usage simply
+is not recorded, because a knowledge fetch must never fail over an analytics table. With no secret
+set at all the service stays open rather than locking everyone out over a missing env var.
+
+Board knowledge is authored once, in `backend/knowledge/`. `build_knowledge.py` is the only bridge:
+it copies the hardware payload here and **deletes** anything carrying a `%%TOKEN%%` — those are
+build-time substitutions belonging to a browser product this one is not part of. Deleted, not
+reworded: hardware knowledge is pins, buses, addresses, libraries, init and timing, and a placeholder
+for someone else's build step is none of those. Everything else passes through as written. Run
+`--check` in CI.
+
+## Boards
+
+| Board | Silicon | Upload |
+|---|---|---|
+| Genesis One / Genesis Mini | ESP32-S3 | `upload` |
+| XIAO Shield (ESP32-S3) | ESP32-S3 | `upload` |
+| XIAO Shield (nRF52840) | nRF52840 | `upload` (Seeed nRF52 core) |
+| Pi HAT | RP2040 | `upload` (mpremote over the Pi UART) |
+
+Verbs are facts of the (board, language), read from `board.json` — not a list in this README.
+
+Python 3.9+. `pyserial` is the only dependency; the build tools install into the private prefix.

axiometa_cli-2.0.0/axiometa_cli/__init__.py

@@ -0,0 +1,34 @@
+"""axiometa-cli — Axiometa hardware from any terminal, editor or agent.
+
+ONE job: the half of the work that can only happen on the machine the board is plugged into.
+
+    board facts  ·  provision a toolchain  ·  compile  ·  flash  ·  read serial
+
+It does NOT generate code. Whatever is driving it — an editor, Claude Code, a build script, a person —
+already does that better than a prompt box in a terminal, and the thing they cannot do is reach a
+board. So the CLI answers "what is this board, exactly" (ports, pins, fqbn, build options, transports)
+and then turns a sketch into a flashed device.
+
+Two properties make that usable inside someone else's project:
+
+  - NO BUNDLED BOARD DATA. Board facts come from the backend (GET /api/knowledge/boards) and are
+    cached locally, so a board or module added to the knowledge tree is available here immediately
+    with no CLI release. One source of truth (knowledge_client.py).
+
+  - A FULLY PRIVATE TOOLCHAIN. Axiometa boards are a custom board package laid into a pinned ESP32
+    core; installing that into a shared arduino-cli would rewrite files other projects depend on. So
+    we ship our own arduino-cli, cores and libraries under ~/.axiometa and never read or touch the
+    user's own (toolchain.py).
+
+A board is shipped here only if it declares an fqbn — something this toolchain can actually build
+and upload. Serving a board it cannot serve would be a promise the tool breaks at the last step.
+"""
+# Read the real installed version from package metadata so `--version` never goes stale.
+try:
+    from importlib.metadata import version as _pkg_version, PackageNotFoundError
+    try:
+        __version__ = _pkg_version("axiometa-cli")
+    except PackageNotFoundError:
+        __version__ = "0.0.0+dev"
+except Exception:
+    __version__ = "0.0.0+dev"

axiometa_cli-2.0.0/axiometa_cli/cli.py

@@ -0,0 +1,349 @@
+"""axiometa — hardware truth, and putting firmware on the board.
+
+Two jobs, for someone else's AI working in someone else's repo:
+
+  FETCH HARDWARE TRUTH   what a board and its parts actually are. An Axiometa board is a custom board
+                         package — its pins, its esp32:esp32:axiometa_* target and its parts match
+                         nothing in a stock core, so none of it is inferable, and a wrong pin map
+                         compiles cleanly and fails silently in hardware.
+
+      axiometa boards
+      axiometa board genesis-one
+      axiometa parts genesis-one
+      axiometa part  genesis-one AX22-0005
+
+  UPLOAD TO THE BOARD    a toolchain that can actually build for these boards, with the libraries
+                         each part declares, and put the result on the device.
+
+      axiometa login <key>
+      axiometa provision
+      axiometa devices
+      axiometa compile ./firmware -b genesis-one --parts AX22-0005
+      axiometa upload  ./firmware -b genesis-one --parts AX22-0005
+
+      axiometa mcp       the same, for clients that speak MCP
+
+Stateless: every command takes what it needs as arguments and writes only inside ~/.axiometa. There
+is no manifest, no project file and no convention about where a sketch lives — the repo belongs to
+whoever is working in it. Whoever is driving writes the code. This does not.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__, core, detect, toolchain, ui
+
+
+def _board(board_id: str) -> dict:
+    boards = core.load_boards()
+    if not boards:
+        ui.err("no board knowledge available. First run fetches it; check the network, or point "
+               "AXIOMETA_KNOWLEDGE at a knowledge/boards folder.")
+        sys.exit(1)
+    b = boards.get(board_id)
+    if not b:
+        ui.err(f"unknown board {board_id!r}. Known: {', '.join(boards)}")
+        sys.exit(1)
+    return b
+
+
+def _sub(board: dict, language: str | None):
+    return core.resolve_substrate(board, language)
+
+
+def _parts_arg(value: str | None) -> list:
+    """Catalog ids the build uses, comma-separated. The CALLER names them — there is no manifest to
+    read them out of, and guessing from #includes is how a build ends up with the wrong library."""
+    return [p.strip() for p in (value or "").split(",") if p.strip()]
+
+
+def _options_arg(values: list | None) -> dict:
+    """--option PartitionScheme=app_max_no_ota, repeatable. Roles resolve against the board's own
+    build_options; an unknown value passes through and surfaces as a normal compile error."""
+    out = {}
+    for v in values or []:
+        if "=" not in v:
+            ui.err(f"--option expects KEY=VALUE, got {v!r}")
+            sys.exit(2)
+        k, val = v.split("=", 1)
+        out[k.strip()] = val.strip()
+    return out
+
+
+# ── hardware truths ──────────────────────────────────────────────────────────────────────────────
+def cmd_boards(args):
+    boards = core.load_boards()
+    if args.json:
+        print(json.dumps(list(boards.values()), indent=2))
+        return
+    for b in boards.values():
+        langs = ", ".join(b.get("languages_available") or [])
+        print(f"  {b['id']:<22} {b.get('name',''):<24} {b.get('silicon',''):<10} "
+              f"{b.get('port_count','?')} ports  [{langs}]")
+
+
+def cmd_board(args):
+    b = _board(args.board_id)
+    lang = args.language if args.language in (b.get("languages_available") or []) else b.get("default_language")
+    sub = _sub(b, lang)
+    root = core.knowledge_root()
+    fw = (root / b["id"] / lang / "firmware") if root and lang else None
+
+    def _read(name):
+        f = fw / name if fw else None
+        return f.read_text(encoding="utf-8") if f and f.is_file() else ""
+
+    if args.json:
+        print(json.dumps({
+            "board": b, "language": lang,
+            "device_program": sub.get("device_program"),
+            "fqbn": sub.get("fqbn"),
+            "fqbn_with_default_profile": core.fqbn_with_options(sub) or None,
+            "build_options": sub.get("build_options") or {},
+            "deploy_verbs": core.verbs_for(sub),
+            "board_specs": _read("board-specs.md"),
+            "contract": _read("contract.md"),
+        }, indent=2))
+        return
+    print(f"{b.get('name')}  ({b['id']})")
+    print(f"  silicon   {b.get('silicon')}   mcu {b.get('mcu')}   ports {b.get('port_count')}   "
+          f"logic {b.get('logic_voltage')}")
+    print(f"  language  {lang}   device program {sub.get('device_program')}")
+    if sub.get("fqbn"):
+        print(f"  fqbn      {core.fqbn_with_options(sub)}")
+    for k, v in (sub.get("build_options") or {}).items():
+        roles = (v or {}).get("roles") or {}
+        print(f"    {k:<16} default={v.get('default')}  roles: {', '.join(roles)}")
+    print(f"  verbs     {', '.join(core.verbs_for(sub))}")
+    specs = _read("board-specs.md")
+    if specs:
+        print()
+        print(specs)
+
+
+def cmd_parts(args):
+    b = _board(args.board_id)
+    lang = args.language if args.language in (b.get("languages_available") or []) else b.get("default_language")
+    parts = core.load_parts(b["id"], lang)
+    if args.json:
+        print(json.dumps(parts, indent=2) if args.full else
+              json.dumps([{"id": p["id"], "name": p.get("name"), "kind": p.get("kind"),
+                           "category": p.get("category")} for p in parts.values()], indent=2))
+        return
+    for p in parts.values():
+        print(f"  {p['id']:<12} {p.get('kind',''):<9} {p.get('name','')}")
+
+
+def cmd_part(args):
+    b = _board(args.board_id)
+    lang = args.language if args.language in (b.get("languages_available") or []) else b.get("default_language")
+    parts = core.load_parts(b["id"], lang)
+    p = parts.get(args.part_id)
+    if not p:
+        ui.err(f"unknown part {args.part_id!r} for {b['id']}/{lang}. List them: axiometa parts {b['id']}")
+        sys.exit(1)
+    print(json.dumps(p, indent=2))
+
+
+def cmd_devices(args):
+    devs = detect.detect()
+    if args.json:
+        from dataclasses import asdict
+        print(json.dumps([asdict(d) for d in devs], indent=2, default=str))
+        return
+    if not devs:
+        ui.warn("no serial devices found.")
+        hint = detect.permission_hint()
+        if hint:
+            ui.hint(hint)
+        return
+    for d in devs:
+        print("  " + d.label())
+
+
+# ── upload methods ───────────────────────────────────────────────────────────────────────────────
+def cmd_provision(args):
+    from . import provision
+    boards = core.load_boards()
+    if not boards:
+        ui.err("no board knowledge available — cannot provision without knowing the boards.")
+        sys.exit(1)
+    sys.exit(0 if provision.provision(boards) else 1)
+
+
+def _build(args, verb: str):
+    b = _board(args.board)
+    lang = args.language if args.language in (b.get("languages_available") or []) else b.get("default_language")
+    sub = _sub(b, lang)
+    src = Path(args.source).expanduser().resolve()
+    if not src.is_dir():
+        ui.err(f"{src} is not a directory (point at the folder holding the device program).")
+        sys.exit(2)
+    # What a part DECLARES, plus whatever the caller wants on top. The catalog is a starting point,
+    # not a fence: a build is free to use any library from the Arduino Library Manager, and --lib is
+    # how it says so. Order matters only in that declared parts come first.
+    libs = core.libraries_for(b["id"], lang, _parts_arg(args.parts))
+    libs += [l for l in (args.lib or []) if l not in libs]
+    verbs = core.verbs_for(sub)
+    if verb == "upload":
+        verb = "deploy" if "deploy" in verbs else ("install" if "install" in verbs else "")
+        if not verb:
+            ui.err(f"{b['id']} declares no upload verb (has {', '.join(verbs)}).")
+            sys.exit(2)
+    return b, sub, src, libs, verb
+
+
+def cmd_compile(args):
+    b, sub, src, libs, _ = _build(args, "compile")
+    if not sub.get("fqbn"):
+        ui.err(f"{b['id']} has no compile step for {sub.get('substrate')} — deploy copies the "
+               f"program to the device instead.")
+        sys.exit(2)
+    ext = sub.get("ext") or Path(sub["device_program"]).suffix
+    entry = core.resolve_entry(src, sub["device_program"], ext)
+    if not entry:
+        ui.err(f"no {sub['device_program']} (or a single {ext} file) in {src}.")
+        sys.exit(2)
+    # arduino-cli needs <folder>/<folder>.ino; stage so any filename in the user's repo works.
+    src = core.stage(src, entry, ext)
+    fqbn = core.fqbn_with_options(sub, _options_arg(args.option))
+    if args.print_command:
+        # The escape hatch. Everything this tool knows that you could not derive is in this one
+        # line: our binary, our config, the resolved target with its build profile. Take it, change
+        # it, script it, run it from your own Makefile — nothing here needs to stay in the loop.
+        print(" ".join(toolchain.ac_cmd("compile", "--fqbn", fqbn, str(src))))
+        return
+    ui.step(f"compile {src.name} → {b.get('name')}  ({fqbn})")
+    failed = toolchain.install_libraries(list(toolchain.REQUIRED_LIBRARIES) + libs,
+                                         on_line=lambda l: print(ui.c("  " + l, "grey")))
+    if failed:
+        ui.warn("could not install: " + ", ".join(failed))
+    r = core._run(toolchain.ac_cmd("compile", "--fqbn", fqbn, str(src)),
+                  on_line=lambda l: print(ui.c("  " + l, "grey")), env=toolchain.env())
+    (ui.ok if r.ok else ui.err)("compiled" if r.ok else r.detail)
+    sys.exit(0 if r.ok else 1)
+
+
+def cmd_upload(args):
+    b, sub, src, libs, verb = _build(args, "upload")
+    port = core.serial_port(sub, args.port)
+    ui.step(f"{verb} {src.name} → {b.get('name')} on {port or '(autodetect)'}")
+    res = core.deploy(b, sub, src, verb, port, declared=_options_arg(args.option), libraries=libs,
+                      on_line=lambda l: print(ui.c("  " + l, "grey")))
+    (ui.ok if res.ok else ui.err)(res.detail.splitlines()[0] if res.detail else "done")
+    sys.exit(0 if res.ok else 1)
+
+
+def cmd_lib(args):
+    """Install or list libraries in the toolchain. Any Arduino Library Manager name works — the
+    catalog decides what a PART needs, never what a build is allowed to use."""
+    if not args.spec:
+        r = core._run(toolchain.ac_cmd("lib", "list"), env=toolchain.env(), timeout=60)
+        print(r.detail)
+        return
+    failed = toolchain.install_libraries(args.spec, on_line=lambda l: print(ui.c("  " + l, "grey")))
+    if failed:
+        ui.err("could not install: " + ", ".join(failed))
+        sys.exit(1)
+    ui.ok(f"installed {len(args.spec)}")
+
+
+def cmd_login(args):
+    """Store the headless key. Get it from studio.axiometa.io -> account menu -> Axiometa Headless."""
+    if not args.key:
+        k = toolchain.key()
+        if k:
+            print(f"{k[:12]}... (stored at {toolchain.key_file()})")
+        else:
+            ui.err("no key stored. Get one at studio.axiometa.io -> account menu -> "
+                   "Axiometa Headless, then:  axiometa login <key>")
+            sys.exit(1)
+        return
+    if not args.key.startswith("axm_"):
+        ui.err("that does not look like a headless key (they start with axm_).")
+        sys.exit(2)
+    ui.ok(f"key saved to {toolchain.save_key(args.key)}")
+
+
+def cmd_mcp(args):
+    from . import mcp
+    sys.exit(mcp.serve())
+
+
+# ── parser ───────────────────────────────────────────────────────────────────────────────────────
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="axiometa",
+                                description="Axiometa hardware truths and upload methods.")
+    p.add_argument("--version", action="version", version=f"axiometa-cli {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def lang(sp):
+        sp.add_argument("-l", "--language", help="runtime; defaults to the board's own default")
+        return sp
+
+    b = sub.add_parser("boards", help="every Axiometa board")
+    b.add_argument("--json", action="store_true"); b.set_defaults(func=cmd_boards)
+
+    bd = lang(sub.add_parser("board", help="one board: ports, pins, fqbn, build options, specs"))
+    bd.add_argument("board_id"); bd.add_argument("--json", action="store_true")
+    bd.set_defaults(func=cmd_board)
+
+    ps = lang(sub.add_parser("parts", help="the catalog for a board"))
+    ps.add_argument("board_id"); ps.add_argument("--json", action="store_true")
+    ps.add_argument("--full", action="store_true", help="every part's full metadata, not just identity")
+    ps.set_defaults(func=cmd_parts)
+
+    pt = lang(sub.add_parser("part", help="one part: pins, library, init, coding rules"))
+    pt.add_argument("board_id"); pt.add_argument("part_id"); pt.set_defaults(func=cmd_part)
+
+    dv = sub.add_parser("devices", help="what is plugged in")
+    dv.add_argument("--json", action="store_true"); dv.set_defaults(func=cmd_devices)
+
+    sub.add_parser("provision", help="install the private toolchain (once per machine)")        .set_defaults(func=cmd_provision)
+
+    def build_args(sp):
+        sp.add_argument("source", help="directory holding the device program")
+        sp.add_argument("-b", "--board", required=True)
+        sp.add_argument("--parts", help="catalog ids this build uses, comma-separated — decides "
+                                        "which libraries get installed")
+        sp.add_argument("--lib", action="append",
+                        help="any other library to install (repeatable), e.g. --lib ArduinoJson@7.0.4")
+        sp.add_argument("--option", action="append",
+                        help="build option, KEY=VALUE (repeatable), e.g. PartitionScheme=app_max_no_ota")
+        return lang(sp)
+
+    cp = build_args(sub.add_parser("compile", help="build for a board with its profile and libraries"))
+    cp.add_argument("--print-command", action="store_true",
+                    help="print the exact toolchain command instead of running it")
+    cp.set_defaults(func=cmd_compile)
+
+    lb = sub.add_parser("lib", help="install or list libraries in the toolchain")
+    lb.add_argument("spec", nargs="*", help="Library Manager names, e.g. 'ArduinoJson@7.0.4'")
+    lb.set_defaults(func=cmd_lib)
+
+    up = build_args(sub.add_parser("upload", help="build and put it on the connected board"))
+    up.add_argument("-p", "--port", help="serial port; autodetected if omitted")
+    up.set_defaults(func=cmd_upload)
+
+    lg = sub.add_parser("login", help="store your headless key (from Studio -> Axiometa Headless)")
+    lg.add_argument("key", nargs="?", help="the axm_... key; omit to show the stored one")
+    lg.set_defaults(func=cmd_login)
+
+    sub.add_parser("mcp", help="the same tools over MCP (stdio)").set_defaults(func=cmd_mcp)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try:
+        args.func(args)
+    except KeyboardInterrupt:
+        print()
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()