@tikoci/centrs 0.1.3 → 0.1.6

package/commands/mcp/README.md

@@ -80,8 +80,8 @@ benchmarked RouterOS agent support. Load-bearing findings that shape this design
   rejected. RouterOS 7.23 no longer reproduces that exact `blackhole=yes` case,
   but the lesson stands: schema-presence is not parser-acceptance.
   `:put [:parse "<cmd>"]` runs the real parser, and centrs runs **both** `:parse`
-  and `/console/inspect`, so the MCP exposes validation as a first-class
-  **dry-run** tool (`centrs_validate`) that never mutates.
+  and `/console/inspect request=child`, so the MCP exposes validation as a
+  first-class **dry-run** tool (`centrs_validate`) that never mutates.
 - **Stateful intents need device-validate-before-apply.** Gold using
   `interface=ether2` fails on a CHR exposing only `ether1`. Pair `execute` with
   cheap readback (`retrieve`).
@@ -104,7 +104,7 @@ benchmarked RouterOS agent support. Load-bearing findings that shape this design
 | Tool | Core mapping | Reads/Writes | Target source |
 | ---- | ------------ | ------------ | ------------- |
 | `centrs_explain` | `canonicalizeExecuteCommand` | offline, none | none (string only) |
-| `centrs_validate` | execute validation only (`:parse` + `/console/inspect`), **no run** | read-only | CDB |
+| `centrs_validate` | execute validation only, **no run**: offline analysis, then the device stage — `:put [:parse ...]` alone over ssh/mac-telnet, `:parse` + `/console/inspect` for structured REST/native | read-only | CDB |
 | `centrs_retrieve` | `retrieve` / `retrieveGroup` | read-only | CDB |
 | `centrs_execute` | `execute` | read or write | CDB |
 | `centrs_devices` | `devices` (`list`/`show`/`groups`/`add`/`edit`/`set`/`remove`) | CDB read/write | CDB file |
@@ -118,7 +118,10 @@ benchmarked RouterOS agent support. Load-bearing findings that shape this design
 - `centrs_validate` is the headline distilled from the bench: a dry-run that runs
   the real parser plus schema inspection against a registered target and returns
   the validation envelope **without executing**. Use it to reject schema-invalid
-  commands before any write.
+  commands before any write. It shares `execute`'s two-stage gate (constitution:
+  validation is the product, GH#354), so a syntax fault comes back from the
+  offline stage with a byte span and without contacting the target at all, and
+  `meta.validation.stages[]` says which stage spoke.
 - `centrs_retrieve` mirrors `retrieve`, including attribute projection,
   `listAttributes`, and `group` fanout.
 - `centrs_execute` mirrors `execute`. Read-shaped commands run subject only to

package/commands/mcp/examples.md

@@ -65,8 +65,8 @@ matters for the bench gold-bug in example 4.
 ```
 
 Envelope: `ok: false`, `error.code = "validation/unknown-attribute"` — the
-`/console/inspect` semantic gate rejects the unknown attribute and **no route is
-created**. This proves the validate tool fails closed on bad input.
+`/console/inspect request=child` semantic gate rejects the unknown attribute and
+**no route is created**. This proves the validate tool fails closed on bad input.
 
 > Bench note: the bench's original gold-bug command
 > `/ip/route/add dst-address=10.99.0.0/24 blackhole=yes` (where `/console/inspect`

package/commands/retrieve/README.md

@@ -43,37 +43,32 @@ centrs retrieve <router> snmp <oid|MIB name> [flags]
 
 ## Flags
 
-| Flag                                | Behavior                                                                                  |
+Implemented flags are generated from the CLI metadata into
+[`docs/CLI.md` → retrieve](../../docs/CLI.md#retrieve); this file does not
+duplicate that table. Behavior notes the generated reference cannot carry:
+
+- `--format json` (shortcut `--json`): set `CENTRS_FORMAT=json` to make the
+  structured envelope the default. `--format yaml` renders the same envelope.
+- `--port`: native-api defaults to 8728; `--port 8729` selects TLS `api-ssl`.
+- `--query`/`--filter` are RouterOS **row** filters and always return an
+  array (see Synopsis); `--where` filters *which devices* fan out, not rows.
+- `--all-attributes` conflicts with `--attribute(s)` (see Validation).
+- `--quickchr` resolves host/port/auth from the live `@tikoci/quickchr`
+  (0.4.5+, optional dependency) descriptor, bypassing CDB/env resolution for
+  those fields.
+
+### Designed, not implemented
+
+Spec-tier flags with no implementation yet — today they fail as unknown flags:
+
+| Flag                                | Designed behavior                                                                          |
 | ----------------------------------- | ----------------------------------------------------------------------------------------- |
-| `--attribute <name>`                | Project a single attribute. Repeatable, or comma-separated.                               |
-| `--attributes <a,b,c>`              | Alias for `--attribute` with comma-separated input.                                       |
-| `--all-attributes`                  | Equivalent to RouterOS `details=true`. Mutually exclusive with `--attribute(s)`.          |
-| `--list-attributes` (alias `--list`) | Return the available attribute names for the path. No `print`/`get` is run.              |
 | `--once`                            | Bounded single read of a monitor-style menu (RouterOS `once`): returns **one** envelope and never follows. Open-ended follow is `api … --stream`. See constitution: protocol selection. |
-| `--query <expr>`                    | RouterOS-side **row** filter (maps to `.query`), repeatable; returns matching rows as an **array**. This is how you read one row by name (`--query name=ether1`). **Not Implemented** yet — returns `validation/not-implemented`. |
-| `--filter <expr>`                   | RouterOS row filter; same `.query` mapping and not-implemented handling as `--query`.       |
-| `--where <attr>=<value>`            | Device-class selector: fan out across CDB records whose stored fact/comment-kv matches (e.g. `--where board=RB5009`). Repeatable (AND). Filters *which devices*, not RouterOS rows. See constitution: target selection. |
-| `--max-bytes <n>`                   | Byte budget for the rendered payload. If the response would exceed it, centrs truncates to fit, keeps `ok: true`, and adds a warning + `meta.truncated`. Not an error. (Renamed from `--max-results`; the legacy flag still parses until the code split lands.) |
+| `--max-bytes <n>`                   | Byte budget for the rendered payload. If the response would exceed it, centrs truncates to fit, keeps `ok: true`, and adds a warning + `meta.truncated`. Not an error. (Will replace the implemented `--max-results`, which fails instead of truncating.) |
 | `--max-rows <n>`                    | Maximum row count for list reads. Excess rows are clipped; `ok: true` with a warning + `meta.truncated`.                                    |
-| `--format text` (default)           | Human-readable rendering (default). Errors print `[code] summary` + `Fix:` lines. |
-| `--format json` (alias `--json`)    | Structured JSON envelope (set `CENTRS_FORMAT=json` to make it the default).               |
-| `--format yaml` (alias `--yaml`)    | YAML rendering of the same envelope.                                                      |
-| `--resolve <none\|arp>`             | Resolve a MAC-address target to an IP via the host ARP cache. Default `none`.             |
-| `--via <protocol>`                  | Pin the transport (`rest-api` default, or `native-api`). No silent downgrade. See constitution: protocol selection. |
-| `--validate=false`                  | Escape hatch; default is `true`. See constitution: validation is the product.             |
-| `--timeout <ms>`                    | Request timeout. REST: ≤ 60000. native-api allows longer.                                 |
-| `--username` (alias `--user`, `-u`) / `--password` | Override CDB-resolved or env credentials.                                                 |
-| `--host <host\|url>`                 | Override the resolved host or base URL for the target.                                     |
-| `--port <n>`                        | Override the transport port. native-api defaults to 8728 (TLS api-ssl when `--port 8729`).|
-| `--cdb-file` / `--cdb-password`     | Override CDB file location / decrypt password.                                            |
+| `--yaml`                            | Shortcut for `--format yaml`.                                                             |
 | `--ros-version <version>`           | SNMP MIB lookup only: pin the MikroTik MIB version to cache/download.                     |
 | `--ros-channel <channel>`           | SNMP MIB lookup only: `stable`, `long-term`, `testing`, or `development`; default `stable`. |
-| `--group <name>`                    | Fan out across every CDB target in WinBox group `<name>`. Repeatable, and combinable with `<router>` positionals plus `--all`/`--default`; the union is de-duped by CDB record index. See **Target selection**. |
-| `--all`                             | Fan out across every CDB record (excludes the reserved `__default__`). See **Target selection**. |
-| `--default`                         | Select the reserved `__default__` record. See **Target selection**. |
-| `--near <lat>,<lon>,<radius>`       | Geo selector: fan out across CDB records whose GPS is within the great-circle radius (units `m`/`km`/`mi`/`ft`; bare = km). Lat-first. Union predicate; geo-less devices never match. See **Target selection**. |
-| `--bbox <south>,<west>,<north>,<east>` | Geo selector: fan out across CDB records whose GPS is inside the lat-first bounding box. Union predicate. See **Target selection**. |
-| `--concurrency <n>`                 | Max in-flight targets during fanout (integer ≥ 1). Defaults are transport-aware: `rest-api` 8, `native-api` 4. Rejected with `usage/invalid-concurrency` otherwise. |
 
 ## Validation
 
@@ -157,7 +152,10 @@ granular **0/2/1 exit code** are all normative in
 [`docs/CONSTITUTION.md` → Target selection grammar](../../docs/CONSTITUTION.md#target-selection-grammar).
 The boundary is intent-keyed: a plain single-positional `retrieve <router> <path>`
 stays the single-target envelope; a selector flag or a second positional target
-switches to fan-out.
+switches to fan-out. `--quickchr <name>` (the named-live-provider) behaves like a
+lone positional: one flag stays single-target, repeating it fans out, and mixing
+it with positionals or CDB selectors is `usage/conflicting-flags` (constitution:
+resolution providers).
 
 retrieve-specific behavior on top of the shared engine:
 

package/commands/retrieve/examples.md

@@ -335,3 +335,19 @@ centrs retrieve $A /system/resource --attribute bogus-attr --via native-api --po
 ```bash
 centrs retrieve $A /system/resource --via native-api --port $API_PORT --username wrong --password wrong
 ```
+
+## quickchr targets (#134)
+
+`$NAME` is the machine name of a running quickchr-managed CHR
+(`quickchr list`). No `$R`/`$U`/`$P` — host/port/auth come from the live
+descriptor. Covered by `test/integration/quickchr-target.test.ts`.
+
+### Q1. `--quickchr <name>` resolves the VM's REST endpoint
+
+```bash
+centrs retrieve --quickchr $NAME /system/resource --json
+```
+
+Envelope: `ok: true`, `meta.via=rest-api` (normal default; quickchr does not
+change protocol selection), `meta.target.source.kind=provider`,
+`meta.target.identity=$NAME`, no `recordIndex` (the CDB was never consulted).

package/commands/terminal/examples.md

@@ -42,6 +42,9 @@ printf '/system/identity/print\n' | centrs terminal $MAC --via mac-telnet --host
 ```
 
 stdout contains the device identity (cross-checked against REST). Exit code `0`.
+RouterOS 7.23.6/7.24.3/7.25beta4 print a one-property menu's value one
+character per line (GH#352), so the comparison collapses `print` column
+wrapping on both sides rather than asserting the device's layout.
 
 ### T2. `--via rest-api` has no terminal capability
 
@@ -99,7 +102,10 @@ analog of T4** (a piped subprocess stdin cannot be a TTY), not in CI.
 printf '/system/identity/print\n/quit\n' | centrs terminal 127.0.0.1 --via ssh --port $SSH_PORT --username $U --ssh-key $KEY --insecure
 ```
 
-stdout contains the device identity (cross-checked against REST). centrs returns
+stdout contains the device identity (cross-checked against REST).
+RouterOS 7.23.6/7.24.3/7.25beta4 print a one-property menu's value one
+character per line (GH#352), so the comparison collapses `print` column
+wrapping on both sides rather than asserting the device's layout. centrs returns
 ssh's exit code (a no-PTY console closed by EOF can exit non-zero — that is the
 device/ssh's result, not a centrs failure; a clean `/quit` from a real TTY exits
 `0`).

package/commands/transfer/README.md

@@ -154,27 +154,35 @@ is an explicit `--via scp` escape hatch. The reason is capability, not taste:
 
 ## Flags
 
-| Flag | Behavior |
-| ---- | -------- |
-| `--via <method>` | Pin the method: `sftp` (built; secure default for large transfers), `rest`, `native`, or `scp` *(deferred)* / `fetch` *(deferred)* / `ftp` *(gated)*. No silent downgrade. See *Method selection* and constitution: protocol selection. |
-| `--force` (alias `--overwrite`) | Replace an existing target. Default **refuses** an existing target with `usage/target-exists` (mirrors how `add` refuses an existing record). Applies to the destination side: the local file for `download`, the remote file for `upload`. |
-| `--verify <size\|checksum\|off>` | Post-transfer integrity check. Default `size` (compare the byte count centrs sent/received against the settled `/file` size). `off` (alias `--no-verify`) skips it. See *Integrity*. |
-| `--type <file\|directory\|disk\|package>` | `list` only: filter by `/file` row type. |
-| `--name <glob>` | `list` only: filter by file name glob. |
-| `--out-dir <dir>` | `download` fan-out only: write one file per target into `<dir>` (named by CDB identity, collision-safe, keeping the remote extension), since N devices cannot share one local path. **Required** for a `download` across a selection. See **Target selection**. |
-| `--yes` | Confirm a mutating fan-out (`upload`/`remove`/`mkdir`/`copy`) across multiple routers in non-interactive runs (confirmed once up front). See **Target selection**. |
+Implemented flags are generated from the CLI metadata into
+[`docs/CLI.md` → transfer](../../docs/CLI.md#transfer); this file does not
+duplicate that table. Behavior notes the generated reference cannot carry:
+
+- `--force`/`--overwrite` applies to the destination side (the local file for
+  `download`, the remote file for `upload`); the default refuses an existing
+  target with `usage/target-exists` (see *Validation*).
+- `--verify` details and the sftp size caveat are in *Integrity*.
+- `--timeout`: `rest`/`native` are per-request ≤ 60000 ms (a chunked read is
+  many short requests, each capped); `sftp` accepts longer for a single large
+  transfer.
+- `--ssh-key` is the same `sshKey` setting as `terminal`/`execute`
+  (`CENTRS_SSH_KEY`, CDB `ssh-key=`); when unset, the ssh-agent /
+  `~/.ssh/config` is used. See `commands/terminal/README.md`.
+- `--insecure` adds a `transport/insecure-trust` warning (constitution:
+  transport trust).
+- `--quickchr` resolves host/port/auth from the live `@tikoci/quickchr`
+  (0.4.5+, optional dependency) descriptor. `--via sftp` additionally
+  requires the descriptor's SSH endpoint to advertise a batch-capable auth
+  mode, else `quickchr/unsupported-via` (never a password prompt).
+
+### Designed, not implemented
+
+Spec-tier flags with no implementation yet — today they fail as unknown flags:
+
+| Flag | Designed behavior |
+| ---- | ----------------- |
 | `--advertise-host <host>` / `--advertise-port <n>` / `--bind <addr>` | `fetch` only *(deferred)*: the host/IP/port centrs advertises in the fetch URL and the local bind address. Default: auto-detect the local IP on the route to the router; ephemeral port; single-use random URL token. |
-| `--resolve <none\|arp>` | *(deferred — not parsed yet)* Resolve a MAC-address target to an IP via the host ARP cache. Default `none`. |
-| `--format text` (default) | Human summary: method, bytes, duration, verified. Errors print `[code] summary` + `Fix:` lines. |
-| `--format json` (alias `--json`) / `--format yaml` (alias `--yaml`) | Structured envelope. `CENTRS_FORMAT=json` makes JSON the default. |
-| `--validate=false` | Escape hatch; default `true`. See constitution: validation is the product. |
-| `--timeout <ms>` | Request timeout. `rest`/`native` per-request ≤ 60000 (a chunked read is many short requests, each capped); `sftp`/`scp`/`fetch` accept longer for a single large transfer. |
-| `--username` / `--password` | Override CDB-resolved or env credentials. |
-| `--host <host\|url>` / `--port <n>` | Override the resolved host / transport port. |
-| `--ssh-key <path>` | `sftp` (and future `scp`): explicit private-key path. Same `sshKey` setting as `terminal`/`execute` (`CENTRS_SSH_KEY`, CDB `ssh-key=`). When unset, the ssh-agent / `~/.ssh/config` is used. See `commands/terminal/README.md`. |
-| `--insecure` | Accept a self-signed TLS cert (`https`/`api-ssl`) or a new SSH host key (TOFU). Default verifies; see constitution: transport trust. Adds a `transport/insecure-trust` warning. |
-| `--cdb-file` / `--cdb-password` | Override CDB file location / decrypt password. |
-| `--group <name>` / `--where <attr>=<value>` / `--near <lat>,<lon>,<radius>` / `--bbox <south>,<west>,<north>,<east>` / `--all` / `--default` / `--concurrency <n>` | Fan out across CDB targets (e.g. push one firmware file to a fleet). Same selector grammar and per-target envelope as `retrieve`/`execute` (constitution: target selection). `--near`/`--bbox` select by device GPS (lat-first). `download` fan-out requires `--out-dir`; `remove`/`mkdir`/`copy`/`upload` fan out directly and are `--yes`-gated. See **Target selection**. |
+| `--resolve <none\|arp>` | Resolve a MAC-address target to an IP via the host ARP cache. Default `none`. |
 
 ## Target selection
 

package/commands/transfer/examples.md

@@ -432,3 +432,32 @@ centrs transfer $R upload $SRC centrs-up.txt --via ftp --username $U --password
 Envelope: `ok: false`, the error reports the protocol is gated (the cleartext-FTP
 opt-in is absent). When `ALLOW_UNSAFE_PROTOCOLS=ftp` is set but the method is not
 yet built, it is `usage/not-implemented` instead.
+
+## quickchr targets (#134)
+
+`$NAME` is the machine name of a running quickchr-managed CHR. Host/port/auth
+come from the live descriptor. Covered by
+`test/integration/quickchr-target.test.ts`.
+
+### Q1. `list` over the descriptor's REST service
+
+```bash
+centrs transfer --quickchr $NAME list --json
+```
+
+Envelope: `ok: true`, `meta.target.source.kind=provider`.
+
+### Q2. `--via sftp` gates on the SSH endpoint's batch auth
+
+```bash
+centrs transfer --quickchr $NAME list --via sftp --json
+```
+
+When the descriptor's SSH endpoint advertises a **usable** batch-capable auth
+mode (`agent-or-config`, or `private-key` together with a verified
+`privateKeyPath` — a bare `private-key` mode with no path does not count), the
+list succeeds over sftp: `meta.via=sftp`, `meta.target.source.kind=provider`,
+`meta.settings.insecure` provider-sourced, and the key path (when one is
+handed over) carried as a provider-sourced `sshKey`. Otherwise the envelope is
+`ok: false` with `error.code=quickchr/unsupported-via` and exit code 1 — a
+typed gate, **never** a password prompt and never a silent fallback to REST.

package/docs/CLI.md

@@ -0,0 +1,353 @@
+# centrs CLI reference
+
+<!-- GENERATED FILE — do not edit. Regenerate with `bun run docs:cli`. -->
+<!-- Source of truth: the CliCommandMetadata objects in src/cli/*.ts -->
+
+Every flag below is generated from the same metadata that renders
+`centrs <command> --help`; CI fails when this file and the metadata drift
+(`bun run docs:cli --check`). Behavior, examples, and designed-but-not-yet
+implemented flags live in each command's `commands/<name>/README.md`.
+
+| Command | Summary |
+| ------- | ------- |
+| [`retrieve`](#retrieve) | Read RouterOS values through the shared core using the selected protocol. |
+| [`execute`](#execute) | Run a RouterOS read or write command via native API, REST, or mac-telnet. |
+| [`api`](#api) | Structured RouterOS API passthrough (gh-api style) over REST or native API. |
+| [`transfer`](#transfer) | Copy files to/from a RouterOS device and manage device files (rest/native/sftp). |
+| [`terminal`](#terminal) | Open an interactive RouterOS console (ssh or mac-telnet). |
+| [`explain`](#explain) | Analyze a RouterOS command offline: canonical form, structure, and syntax diagnostics. |
+| [`devices`](#devices) | Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB. |
+| [`discover`](#discover) | Discover RouterOS neighbors over MNDP and optionally save them into the CDB. |
+| [`btest`](#btest) | Run MikroTik's bandwidth test as a client or server (peer measurement). |
+| [`mcp`](#mcp) | Start the centrs MCP server (stdio) — scoped RouterOS tools gated by the CDB allowlist. |
+| [`settings`](#settings) | Manage centrs's own global preferences (`centrs.env`) and inspect the `__default__` CDB record. |
+
+## retrieve
+
+Read RouterOS values through the shared core using the selected protocol.
+
+```text
+Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <target...> <routeros-path> [flags] | centrs retrieve --group <name> <routeros-path> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--via` | `<protocol>` | Pin the protocol selector. Defaults to `rest-api` for retrieve. |
+| `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
+| `--where` | `<attr>`=`<value>` | Device-class selector over CDB facts + core fields (repeatable, AND-combined). |
+| `--near` | `<lat>`,`<lon>`,`<radius>` | Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first. |
+| `--bbox` | `<south>`,`<west>`,`<north>`,`<east>` | Geo selector: devices whose GPS is inside the lat-first bounding box. |
+| `--all` |  | Fan out across every CDB record (excludes `__default__`). |
+| `--default` |  | Select the reserved `__default__` record. |
+| `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
+| `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
+| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL for the target. |
+| `--port` | `<port>` | Override the resolved management port. |
+| `--username / --user / -u` | `<name>` | RouterOS username (aliases `--user`, `-u`). Falls back to `CENTRS_USERNAME`. |
+| `--password` | `<secret>` | RouterOS password. Falls back to `CENTRS_PASSWORD`. |
+| `--timeout` | &lt;ms\|5s&gt; | Operation timeout. REST currently rejects values above 60s. |
+| `--attribute` | `<name>` | Project one attribute. May be repeated. |
+| `--attributes` | `<a,b>` | Project a comma-separated attribute list. |
+| `--all-attributes` |  | Request the RouterOS detail/all-attributes shape. |
+| `--list-attributes / --list` |  | List inspect-derived attributes without running the data call. |
+| `--query / --filter` | `<expr>` | RouterOS-side row filter (maps to `.query`). Not implemented yet — returns `validation/not-implemented`. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. Defaults to text; use --json or --format json for the structured envelope. |
+| `--json` |  | Shortcut for `--format json`. |
+| `--max-results` | `<bytes>` | Fail instead of printing output larger than the given byte budget. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
+| `--validate / --no-validate` |  | Enable or disable inspect-backed preflight validation. |
+| `--verbose` |  | Show resolved setting sources in text output. |
+
+## execute
+
+Run a RouterOS read or write command via native API, REST, or mac-telnet.
+
+```text
+Usage: centrs execute <target> <command> [flags] | centrs execute <target...> -- <command> [flags] | centrs execute --group <name> <command> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--via` | &lt;native-api\|rest-api\|mac-telnet&gt; | Pin the protocol selector; no silent downgrade when set. A bare MAC target defaults to mac-telnet. |
+| `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
+| `--where` | `<attr>`=`<value>` | Device-class selector over CDB facts + core fields (repeatable, AND-combined). |
+| `--near` | `<lat>`,`<lon>`,`<radius>` | Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first. |
+| `--bbox` | `<south>`,`<west>`,`<north>`,`<east>` | Geo selector: devices whose GPS is inside the lat-first bounding box. |
+| `--all` |  | Fan out across every CDB record (excludes `__default__`). |
+| `--default` |  | Select the reserved `__default__` record. |
+| `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
+| `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
+| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL for the target. |
+| `--port` | `<port>` | Override the resolved management port. |
+| `--username / --user / -u` | `<name>` | RouterOS username (aliases `--user`, `-u`). Falls back to `CENTRS_USERNAME`. |
+| `--password` | `<secret>` | RouterOS password. Falls back to `CENTRS_PASSWORD`. |
+| `--ssh-key` | `<path>` | `--via ssh`: explicit private-key path. Falls back to `CENTRS_SSH_KEY` / the `ssh-agent`. |
+| `--insecure` |  | Disable SSH host-key verification (`--via ssh`: accepts changed/impersonated keys, not just new) or accept a self-signed `api-ssl` TLS cert. Default verifies. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
+| `--timeout` | `<duration>` | Per-request timeout (for REST, max 60s). |
+| `--validate / --no-validate` |  | Run RouterOS :parse and /console/inspect validation before execution (default true; `--validate=false` also accepted). |
+| `--yes` |  | Confirm write-shaped add/set/remove commands in non-interactive runs. |
+| `--max-results` | `<bytes>` | Fail if the rendered envelope exceeds this byte budget. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. Defaults to text; use --json or --format json for the structured envelope. |
+| `--json` |  | Shortcut for `--format json`. |
+| `--verbose` |  | Include additional context in text output. |
+| `--` |  | End centrs option parsing: every following token is the literal RouterOS command, even flag-shaped ones (e.g. `-- /interface print where disabled=yes`). |
+
+## api
+
+Structured RouterOS API passthrough (gh-api style) over REST or native API.
+
+```text
+Usage: centrs api <router> <endpoint> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `-X / --method` | `<verb>` | HTTP method, default GET (case-insensitive). GET→print, PUT→add, PATCH→set, DELETE→remove, POST→run. |
+| `-f / --field` | `<key=value>` | Body field, repeatable; assembled into the JSON body (verbatim string values). |
+| `-d / --data` | `<json>` | Raw JSON request body. Conflicts with `-f` / `--input`. |
+| `--input` | &lt;file\|-&gt; | Read the raw JSON body from a file or stdin (`-`). |
+| `--query / --filter` | `<expr>` | RouterOS-side row filter, AND-combined, repeatable: name=value, name!=value, name>value, name<value, name. |
+| `--raw-query` | `<word>` | Verbatim RouterOS query word (repeatable) for OR / absence / stack expressions. |
+| `--attribute / --proplist` | `<a,b>` | Property projection → `.proplist`. |
+| `--raw` |  | Strip the envelope; emit bare RouterOS JSON. Defaults `--validate` to false (an explicit `--validate=true` still runs the gate); does not imply `--yes`. |
+| `--yes` |  | Confirm a mutating (non-read) request in non-interactive runs. |
+| `--stream / --listen` |  | Follow changes as an NDJSON envelope stream (native-api only; the `/listen` endpoint infers it). Ends with a summary envelope. |
+| `--count` | `<n>` | Stop a `--stream` after N change frames. |
+| `--duration` | `<dur>` | Stop a `--stream` after this wall-clock window (e.g. `5s`). |
+| `--via` | &lt;rest-api\|native-api&gt; | Pin the transport; no silent downgrade. Default rest-api. |
+| `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
+| `--where` | `<attr>`=`<value>` | Device-class selector over CDB facts + core fields (repeatable, AND-combined). |
+| `--near` | `<lat>`,`<lon>`,`<radius>` | Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first. |
+| `--bbox` | `<south>`,`<west>`,`<north>`,`<east>` | Geo selector: devices whose GPS is inside the lat-first bounding box. |
+| `--all` |  | Fan out across every CDB record (excludes `__default__`). |
+| `--default` |  | Select the reserved `__default__` record. |
+| `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
+| `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
+| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL for the target. |
+| `--port` | `<port>` | Override the resolved management port. |
+| `--username / --user / -u` | `<name>` | RouterOS username. Falls back to `CENTRS_USERNAME`. |
+| `--password` | `<secret>` | RouterOS password. Falls back to `CENTRS_PASSWORD`. |
+| `--insecure` |  | Accept a self-signed `api-ssl`/REST TLS cert. Default verifies. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--resolve` | &lt;none\|arp&gt; | Resolve a MAC-address target to an IP via the host ARP cache (default none). |
+| `--timeout` | `<duration>` | Per-request timeout (for REST, max 60s). |
+| `--validate / --no-validate` |  | Run `/console/inspect` validation before the request (default true; `--validate=false` also accepted). |
+| `--format` | &lt;json\|yaml\|text&gt; | Output format. Defaults to json for api; `CENTRS_FORMAT` overrides. |
+| `--json` |  | Shortcut for `--format json`. |
+| `--verbose` |  | Include additional context in text output. |
+
+## transfer
+
+Copy files to/from a RouterOS device and manage device files (rest/native/sftp).
+
+```text
+Usage: centrs transfer <router> upload <local> [remote] | download <remote> [local] | list [path] | remove <remote> | mkdir <remote> | copy <src> <dst> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--via` | `<method>` | Pin the method: rest, native, or sftp (large transfers); scp/fetch/ftp are not built yet. Auto picks the cheapest by size/direction. |
+| `--ssh-key` | `<path>` | sftp only: explicit private-key path. Falls back to CENTRS_SSH_KEY / the ssh-agent. |
+| `--insecure` |  | Accept a self-signed TLS cert (https/api-ssl) or a new SSH host key. Default verifies. |
+| `--force / --overwrite` |  | Replace an existing destination. Default refuses it. |
+| `--group` | `<name>` | Fan out across every CDB record in the group (repeatable; de-duped by record index). |
+| `--where` | `<attr>`=`<value>` | Device-class selector over CDB facts + core fields (repeatable, AND-combined). |
+| `--near` | `<lat>`,`<lon>`,`<radius>` | Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first. |
+| `--bbox` | `<south>`,`<west>`,`<north>`,`<east>` | Geo selector: devices whose GPS is inside the lat-first bounding box. |
+| `--all` |  | Fan out across every CDB record (excludes `__default__`). |
+| `--default` |  | Select the reserved `__default__` record. |
+| `--quickchr` | `<name>` | Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it). |
+| `--concurrency` | `<n>` | Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4). |
+| `--out-dir` | `<dir>` | `download` fan-out only: write one file per target into `<dir>`, named by CDB identity. Required when downloading across a selection. |
+| `--yes` |  | Confirm a mutating fan-out (upload/remove/mkdir/copy) across multiple routers in non-interactive runs. |
+| `--verify / --no-verify` | &lt;size\|checksum\|off&gt; | Post-transfer integrity check. Default size; `--no-verify` skips. |
+| `--type` | &lt;file\|directory\|disk\|package&gt; | list filter: RouterOS /file row type. |
+| `--name` | `<glob>` | list filter: file-name glob. |
+| `--host` | &lt;host\|url&gt; | Override the resolved host or base URL. |
+| `--port` | `<port>` | Override the resolved management port. |
+| `--username / --user / -u` | `<name>` | RouterOS username (aliases --user, -u). Falls back to CENTRS_USERNAME. |
+| `--password` | `<secret>` | RouterOS password. Falls back to CENTRS_PASSWORD. |
+| `--timeout` | &lt;ms\|5s&gt; | Operation timeout. REST rejects values above 60s. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format. Defaults to text; --json / --yaml shortcuts. |
+| `--json` |  | Shortcut for --format json. |
+| `--yaml` |  | Shortcut for --format yaml. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--validate / --no-validate` |  | Enable or disable the existence-probe preflight. |
+| `--verbose` |  | Show the resolved transport in text output. |
+
+## terminal
+
+Open an interactive RouterOS console (ssh or mac-telnet).
+
+```text
+Usage: centrs terminal <router> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--via` | `<method>` | Transport: `ssh` (host target, default) or `mac-telnet` (MAC target, default for a MAC). rest/native have no terminal capability. |
+| `--host` | `<host>` | Override the target host (ssh) / UDP delivery host (mac-telnet, default L2 broadcast). |
+| `--port` | `<port>` | Override the port: ssh default 22, mac-telnet default 20561. |
+| `--username / --user / -u` | `<name>` | RouterOS username (aliases --user, -u). Falls back to CENTRS_USERNAME. |
+| `--password` | `<secret>` | RouterOS password. Falls back to CENTRS_PASSWORD. |
+| `--source-mac` | `<mac>` | mac-telnet: explicit in-packet source MAC (overrides egress resolution). |
+| `--ssh-key` | `<path>` | `--via ssh`: explicit private-key path. Falls back to `CENTRS_SSH_KEY` / the `ssh-agent`. |
+| `--insecure` |  | `--via ssh`: disable host-key verification (accepts changed/impersonated keys). Default verifies. |
+| `--cdb-file` | `<path>` | Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | Decrypt an encrypted WinBox CDB file. |
+| `--resolve` | &lt;none\|arp&gt; | `--via ssh` only: turn a MAC target into an IP. CDB-first; `arp` opts into the host ARP cache (default none). The mac-telnet default ignores it. |
+| `--format` | &lt;text\|json\|yaml&gt; | Error-envelope format on failure. --json / --yaml shortcuts. |
+| `--json` |  | Shortcut for --format json. |
+| `--yaml` |  | Shortcut for --format yaml. |
+| `--verbose` |  | Verbose error output. |
+
+## explain
+
+Analyze a RouterOS command offline: canonical form, structure, and syntax diagnostics.
+
+```text
+Usage: centrs explain '<input>' [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--file` | `<path>` | Read the input from a file instead of the positional (`-` reads stdin). Piped stdin is used automatically when no input positional is given. |
+| `--fail-on` | &lt;error\|warning\|never&gt; | Exit 2 when the verdict reaches this severity. Default `error`; an ambiguous or unknown statement is a warning, never an error. |
+| `--complete` |  | Continuation candidates at the cursor. Live evidence — offline emits a tip and enumerates nothing. |
+| `--schema` |  | Path enumeration (verbs, args, types, enums). Live evidence — offline emits a tip and enumerates nothing. |
+| `--curl` |  | Render a ready-to-edit REST curl for statements covered by a runtime-tested mapping rule. |
+| `--tokens` |  | Emit the total, gapless token partition behind `data.tokens[]` (every byte not claimed by an analyzer is `unclassified`). |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
+| `--json` |  | Shortcut for `--format json`. |
+| `--yaml` |  | Shortcut for `--format yaml`. |
+| `--verbose` |  | Verbose error output. |
+
+## devices
+
+Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB.
+
+```text
+Usage: centrs devices <list|show|groups|add|edit|set|remove> [args] [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--cdb-file` | `<path>` | Override the resolved CDB path (default `~/.config/tikoci/winbox.cdb`). |
+| `--cdb-password` | `<secret>` | Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used to re-encrypt on writes. |
+| `--via` | `<protocol>` | Resolve and report the protocol source for provenance examples; no network IO is performed. |
+| `--group` | `<name>` | `list` filter / `add`,`edit` first-class group field for the target entry. |
+| `--where` | `<attr=value>` | `list` only — repeatable device-class filter over CDB facts (AND-combined), e.g. `--where lat=37.7749`. |
+| `--near` | `<lat>`,`<lon>`,`<radius>` | `list` only — GPS filter: devices within radius (m/km/mi/ft; bare number = km). Lat-first. |
+| `--bbox` | `<south>`,`<west>`,`<north>`,`<east>` | `list` only — GPS filter: devices inside the lat-first bounding box. |
+| `--members` |  | `groups` only — expand each group's membership. |
+| `--explain` |  | `show` only — include the raw `WinBoxCdbRecord` in `data.record`. |
+| `--match` | &lt;user=…\|target=…\|record-type&gt; | `show` — disambiguate when `<router>` matches several records: `user=<name>`, `target=<addr>`, or a record-type token. |
+| `--user` | `<name>` | `add`,`set` — first-class CDB user field. |
+| `--password` | `<secret>` | `add`,`set` — first-class CDB password field. |
+| `--profile` | `<name>` | `add`,`set` — named WinBox profile (Workspace). |
+| `--profile-none` |  | `add`,`set` — write the WinBox `<none>` profile sentinel. |
+| `--profile-own` |  | `add`,`set` — write the WinBox `<own>` profile sentinel. |
+| `--session` | `<name>` | `add`,`set` — first-class CDB session field. |
+| `--comment` | `<text>` | `add` only — base free-form comment (may include kv-soup). |
+| `--record-type` | &lt;macTarget\|ipAdmin\|ipUser\|romonNeighbor\|romonTarget&gt; | `add` only — record type (default `ipAdmin`). |
+| `--lat / --latitude` | `<deg>` | `add`,`set` — latitude in decimal degrees (-90..90); a comment-kv fact, paired with --lon. |
+| `--lon / --lng / --longitude / --long` | `<deg>` | `add`,`set` — longitude in decimal degrees (-180..180); a comment-kv fact, paired with --lat. |
+| `--altitude / --alt / --ele / --elevation` | `<meters>` | `add`,`set` — altitude in meters (may be negative); a comment-kv fact. |
+| `--altitude-type / --alt-type` | &lt;MSL\|AGL&gt; | `add`,`set` — vertical datum for --altitude (default MSL); case-insensitive. |
+| `--gps` | `<lat>`,`<lon>`[,`<altitude>`[,`<altitude-type>`]] | `add`,`set` — combined lat,lon[,altitude[,altitude-type]] convenience (lat-first; missing altitude-type defaults MSL). |
+| `--force` |  | `add` only — overwrite the existing (target, user) entry. |
+| `--strict` |  | `add`,`set` — reject unknown comment kv keys instead of warning. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
+| `--json` |  | Shortcut for `--format json`. |
+
+## discover
+
+Discover RouterOS neighbors over MNDP and optionally save them into the CDB.
+
+```text
+Usage: centrs discover [--timeout 15s] [--save] [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--timeout` | &lt;ms\|15s&gt; | Listen window before results are returned. Default 15s. |
+| `--save` |  | Persist discovered neighbors into the CDB (`group=discovered`, `source=mndp`). |
+| `--group` | `<name>` | `--save` group for new entries. Default `discovered`. |
+| `--port` | `<port>` | UDP port to bind for MNDP. Default 5678. |
+| `--cdb-file` | `<path>` | `--save` CDB path override (default `~/.config/tikoci/winbox.cdb`). |
+| `--cdb-password` | `<secret>` | `--save` password for an encrypted CDB. Used to decrypt the existing CDB and re-encrypt on write. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
+| `--json` |  | Shortcut for `--format json`. |
+
+## btest
+
+Run MikroTik's bandwidth test as a client or server (peer measurement).
+
+```text
+Usage: centrs btest <client <router>|server> [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--protocol` | &lt;udp\|tcp&gt; | (client) Transport. Default udp. |
+| `--direction` | &lt;receive\|transmit\|both&gt; | (client) Test direction. Default receive. |
+| `--duration` | `<dur>` | Bound the run (e.g. 15s). Omit for open-ended (Ctrl-C). |
+| `--interval` | `<dur>` | Report cadence (20ms..5s). Default 1s. |
+| `--connection-count` | `<n>` | (client, TCP only) Parallel TCP data connections (1..255). |
+| `--local-udp-tx-size` | `<n>` | (client, UDP only) Client→server packet size (28..64000). |
+| `--remote-udp-tx-size` | `<n>` | (client, UDP only) Server→client packet size (28..64000). |
+| `--local-tx-speed` | `<bps>` | (client) Cap on client→server rate (e.g. 100M). |
+| `--remote-tx-speed` | `<bps>` | (client) Cap on server→client rate (e.g. 100M). |
+| `--random-data` |  | (client) Incompressible payload. |
+| `--nat-mode` |  | (client, UDP only) Originate an outbound datagram first so server→client data can traverse NAT. Automatic when the test receives. |
+| `--authenticate / --no-authenticate` |  | (server) Require EC-SRP5 auth. Default true; `--authenticate=false` also accepted. |
+| `--bind` | `<addr>` | (server) Listen address. Default 127.0.0.1. |
+| `--allocate-udp-ports-from` | `<n>` | (server) Base of the UDP data-port range. Default 2001. |
+| `--max-sessions` | `<n>` | (server) Concurrent test cap (1..1000). Default 100. |
+| `--user / --username / -u` | `<name>` | Credential (aliases --username, -u; falls back to CDB / CENTRS_USERNAME). |
+| `--password` | `<secret>` | Credential (falls back to CDB / CENTRS_PASSWORD). |
+| `--port` | `<port>` | Control port. Default 2000. |
+| `--cdb-file` | `<path>` | (client) Read target credentials from a WinBox CDB file. |
+| `--cdb-password` | `<password>` | (client) Decrypt an encrypted WinBox CDB file. |
+| `--format` | &lt;text\|csv\|json\|yaml&gt; | Output format. Default text. |
+| `--csv` |  | Shortcut for `--format csv`. |
+
+## mcp
+
+Start the centrs MCP server (stdio) — scoped RouterOS tools gated by the CDB allowlist.
+
+```text
+Usage: centrs mcp [start] [--cdb-file <path>] [--allow-adhoc-targets]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--cdb-file` | `<path>` | CDB allowlist path (default `~/.config/tikoci/winbox.cdb`, or CENTRS_CDB_FILE). |
+| `--cdb-password` | `<password>` | Decrypt password for an encrypted CDB (or CENTRS_CDB_PASSWORD). |
+| `--allow-adhoc-targets` |  | Reserved unsafe escape hatch for future inline targets; current tools still use CDB-only targets. |
+| `--help` |  | Show this help. |
+
+## settings
+
+Manage centrs's own global preferences (`centrs.env`) and inspect the `__default__` CDB record.
+
+```text
+Usage: centrs settings [print|get|set|reset] [args] [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--all` |  | `print` only — also list unrecognized CENTRS_* lines found in the file. |
+| `--cdb-file` | `<path>` | `print` only — CDB to probe for the `__default__` record summary (falls back to normal CDB resolution; never centrs.env). |
+| `--cdb-password` | `<secret>` | `print` only — decrypt password for the probed CDB. |
+| `--skip-env-file` |  | `print` only — note that other commands in this environment would not see centrs.env (settings itself always reads the real file). |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
+| `--json` |  | Shortcut for `--format json`. |
+| `--help` |  | Show this help. |