Files
mesh-catalog/modules/mesh-cli/README.md
T
jschoubben 3ff4df5c6e mesh-cli: nox licence is the licences' overview; the controller's leftovers go
The operator typed `nox licence` and got the retired controller's refusal
instead of the licences. `nox licence` and `nox licence list` now call the
licence manager's licences and bindings and print one table of each, every
time local (1126/AC1); `nox licence usage [<licence>]` prints the usage
readings as a table (1126/AC2). `--json` prints the raw answer on every
rendered line, `nox nodes` included: one behaviour for one flag; for the
two calls one object {licences, bindings} (1126/AC3).

In the same change, the operator (2026-11-22 20:41): "why are there still
references to the controller?". Every retired controller line nox answered
with "this was the controller's" (its `instead` lines and the `unowned`
map) is deleted with its text: none has a seat verb of the same job; a
retired line now answers "is not a command" with exit 2, and nothing nox
prints names the controller (1126/AC4). The comments, help and README no
longer name the controller or issue 1126.

Builds: issue 1126 note 151, answers 1-5, and the note after it (acceptance
1126/AC1..AC4, the operator's 20:41 line); one-question-one-tool;
principle 4, a module is steered by its tools.
2026-11-22 20:50:22 +01:00

83 lines
5.2 KiB
Markdown

# mesh-cli
The operator's command on every node: `mesh-cli <command line>`, in interactive zsh also `nox`. Each line calls the
seat verb or the module tool that owns its job, through this machine's console, and prints the owner's answer.
```
nox status
nox conditions --severity urgent
nox deliveries
nox assign <node> <module> --why <text>
nox issue <number>
nox call <node>/node-service-manager.status '{"unit":"plex"}'
nox help
```
## What it places
| What | Where | How |
|---|---|---|
| the program | `/usr/local/bin/mesh-cli` | the `program` bundle, unpacked by an `archive` resource: the node-engine moves the one file in, refuses to write over a file it did not place, and takes out only that file when the module goes |
| the console's address | `/etc/mesh-cli/console` | a file resource from `files/console`: `http://127.0.0.1:${bound:mcp-endpoint:port}/mcp`, from the `mcp-endpoint` the module requires |
| the alias `nox` | the zsh module's mesh block in `~/.zshrc` | a `shell` contribution in the `normal` slot (ADR 0204) |
No link and no second copy. `/usr/local/bin` is on every account's `PATH` already. The alias is interactive zsh only:
a script, `sudo`, a cron line and any document meant to work everywhere say `mesh-cli`. In interactive zsh the alias
hides any other `nox` (Arch's `python-nox` installs `/usr/bin/nox`); `command nox` still reaches it.
## How it is answered
`mesh-cli` holds no credential and has no bus account of its own (so its manifest declares no `invokes`: an account
nothing dials would only be minted and kept). It calls `mesh_call` on this machine's console, the mesh MCP server the
module node-tools serves on loopback (novox/hq ADR 0152: whoever is on the machine owns the mesh there), and the console
puts the call on the bus, as every agent session on the machine does. The console's address is read from
`/etc/mesh-cli/console`, or `MESH_CONSOLE` when set, or node-tools' declared port when the file is not there yet.
- **Who judges.** The seat that owns the job: a change of assignments is a proposal the operator approves
(`mesh-module-assigner.propose`), a config value is set with its why (`mesh-config.config`), a silence or a hand act is
recorded as one.
- **The map.** Every line nox takes, and the seat verb or tool that does its job, is `commands.go`'s table. A line
nox does not know, or cannot read, says so and how lines are found or written, and exits 2 having called nothing.
- **Any address.** `nox call <address> [json]` calls any seat verb or tool; `nox search <words>` and
`nox describe <address>` find one and its arguments.
- **What is printed.** The owner's answer as the console gave it (JSON), or the line's table (`nox nodes`,
`nox licence`, `nox licence usage`; `--json` prints the answer raw), on standard output with exit 0; an answer the
console marks an error (a refusal, nothing serving, no answer within its bound) on standard error with exit 1. A
console that does not answer is said as nothing having been called; no answer in time is said as a call that may
have run.
- **`nox status`** is the delivery view's (`mesh-delivery-view.view_status`). When the view does not answer, nox says
so first, shows the open conditions and the deliveries under their own addresses, and exits 1: they are never
passed off as the status.
- **`nox licence`** (and `nox licence list`) is the operator's overview of the licences in one line
(one-question-one-tool): the licence manager's `licences` as one table (licence, kind, bound nodes, weekly, session
and sonnet usage with their resets, the token's expiry, failures, conditions, whether it is the target), then its
`bindings` (node, licence, since, why), every time local; with `--json` the two answers as one object
`{licences, bindings}`. `nox licence usage [<licence>]` is the manager's `usage` readings as a table.
- **`nox enrol open --key <file>`** runs here and asks nothing of the mesh (ADR 0587 §8).
A process that runs for a verb (it carries `MESH_VERB`) is refused before anything is called: a verb is never the
operator.
## What it does not do yet
- **No formatting beyond `nox nodes` and the licence lines.** Answers are the owners' JSON.
- **No line without a seat verb.** Accepting a secret from a person, making or setting the operator key, opening a
sealed secret locally, registering a module from another repository and forgetting a module have no seat verb yet,
so nox has no line for them.
## Tests
`go test ./...`: every owned line calls its owner's address with the arguments it reads, against a stand-in console
answering MCP `tools/call` as node-tools does; a line not known or not read calls nothing and says why; the licence
lines print their tables from the manager's answers; an error
answer, a silent console and a verb's process are said; the status's fallback is labelled and exits 1; the console's
address is found; `enrol open` opens a sealed token locally; the module places the program and the console's address
and nothing else.
## Files it does not know
Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
- `/usr/local/bin`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
- `/etc/mesh-cli`: the program's; it holds the console's address alone.