@tikoci/centrs 0.1.9-next.27 → 0.1.9

package/CHANGELOG.md

@@ -10,13 +10,24 @@ Each stable version has one section. Work in progress goes under
 `## X.Y.Z — next`, which is what `@next` installs (`X.Y.Z-next.N`); the stable
 release dates that heading. A `-next.N` build has no section of its own.
 
-## 0.1.9 — next
+## 0.1.9 — 2026-11-03
 
-In progress on npm tag `next`. The `0.1.9-next.0` cut (2026-10-13) carried
-part of this section.
+The `0.1.9-next.0` preview cut (2026-10-13) carried part of this section.
 
 ### Added
 
+- `explain` publishes a syntactic statement tree (#497, #522): statement
+  `id`/`parent`, substitution `owner`, and block ownership/index links let
+  consumers locate nested source without inferring ancestry from spans.
+  Stored script and callback bodies remain opaque; ownership does not claim
+  execution or lexical inheritance.
+- `devices add`/`set --password-stdin` reads the record password from stdin,
+  so automation can write a credential without it showing in argv or `ps`
+  (#582). One trailing `\n` or `\r\n` is stripped. Empty input is
+  `input/empty-stdin`, non-UTF-8 bytes or a leading byte-order mark are
+  `input/invalid-stdin`, a terminal on stdin is `usage/stdin-is-tty`, and
+  combining it with `--password` is `usage/conflicting-flags`. Other `devices`
+  subcommands refuse the flag.
 - `explain` offers a non-applied repair tip for pasted console prompts
   (#370, #567, #578), including `[user@host] /menu>` and HotLock `>>` forms.
   The candidate preserves command separators and names the menu context;
@@ -117,6 +128,20 @@ part of this section.
 
 ### Changed
 
+- Bun 1.4.4 is the minimum supported version (`engines.bun: >=1.4.4 <2`, was
+  `>=1.3.11 <2`). The CI/release/Pages `packageManager` pin, Docker image and
+  `@types/bun` now use 1.4.4 together (0.1.8 shipped on 1.3.14; #438).
+- **Breaking:** `devices show`, `add` and `set` no longer print the record password
+  (#551). Text and JSON carry `passwordSet: boolean` instead, and
+  `--show-password` on those three subcommands opts back in; other subcommands
+  refuse the flag. The `--explain` record's password field reads `<redacted>`
+  unless the flag is given, as does an unknown-tcode tail that may hold the
+  password. **Library consumers:** exported `showDevice`,
+  `addDevice` and `setDevice` now redact too. `DevicesShowItem` has no
+  `password` field; pass `showPassword: true` to get
+  `DevicesShowItemWithPassword`. MCP output is unchanged (it already redacted)
+  and now uses the same core redaction. Dialing with CDB credentials is
+  unaffected: the resolver and MCP allowlist read the raw record.
 - **Breaking:** permission and edge-auth failures get their own error codes
   (#541). Three codes change for `--json` and library readers:
   - A REST policy refusal (HTTP 500 `not enough permissions (9)` or `std
@@ -203,9 +228,7 @@ part of this section.
   `/cmr/upgrade/trigger`, `/cmr/upgrade/job/run-next`) are pinned as writes in
   every spelling, over `execute`, `api` and MCP `mcp=ro`. On 7.26beta1 a
   controller login with only `read` + `api` can run them (#456).
-- CI, release, Pages and the Docker image run Bun 1.4.2 (was 1.3.14), the
-  version local development already used; `@types/bun` moves with it (#438).
-  `engines.bun` stays `>=1.3.11 <2`. The `typescript` peer stays `^6.0.3`:
+- The `typescript` peer stays `^6.0.3`:
   the source passes `tsc --noEmit` under TypeScript 7.0.2, but typedoc 0.28 (the
   API reference build) supports TypeScript up to 6.0.x only.
 - QA records a CHR leg in `qa-history` only when its test step passed or
@@ -223,6 +246,31 @@ part of this section.
 
 ### Fixed
 
+- Help now lists SSH for `execute --via`, the offline analyzer before device
+  validation for `execute` and `api /execute`, and `devices --match` on
+  `show`/`set`/`remove`. `devices --group` names `add`/`set`, and
+  `devices init --help` / `encrypt --help` show only the flags they accept.
+  The generated CLI reference includes both file-command help sections.
+- Offline `explain` withdraws unsupported readings of unlisted bare paths
+  and space-for-`=` arguments (#211, #350), distinguishes command operands
+  from menu blocks (#496), and correctly reads `where` arrays, column-0
+  array comments and nested relative submenu blocks (#502, #503, #351).
+- Offline `explain` rejects CHR-grounded group, operator, escape, variable,
+  name and glued-token faults (#505, #511, #506, #518), including unquoted
+  `?`, backticks, second argument `=` and non-ASCII bytes (#358, #371).
+  Quoted values and accepted controls retain their supported readings.
+  A stray top-level `}` or `]` warns `discarded-close` and marks the
+  unread tail; the execution gate refuses it because RouterOS would discard
+  part of the submitted script (#504).
+- `explain` block spans use analyzed UTF-8 byte offsets, matching statements
+  and tokens even after Unicode text (#523, #524).
+- `settings get <attr>` works in text mode (#587). It crashed reading
+  `typed.source` because the text renderer treated `get`'s single entry as
+  `print`'s key-to-entry map; `--json` was unaffected. It now prints one
+  `key: value [source: …]` line in `print`'s format, under the canonical attr
+  name, and the JSON envelope names that key in `meta.operation.attr`. A fault
+  after the arguments parse is now `internal/settings-failed` (exit 1), not
+  `input/invalid-command` with `--help` advice.
 - **`retrieve` and `api` can no longer send a non-read** (#586). A `#` or
   `?` in the path cut the appended `/print` off the REST URL, so
   `retrieve '/system/reboot#' --no-validate --attribute uptime` posted
@@ -343,6 +391,16 @@ part of this section.
 
 ### Maintenance
 
+- QA allows 50 minutes per CHR leg so the full integration suite can finish
+  (#611).
+- The explain corpus uses schema 5 and one reader, with pinned channel
+  sessions, a regenerated highlight slice and a wiresage conformance gate
+  (#498, #514, #515). Bounded-execution tests use deterministic structural
+  work guards instead of depth-cap timing (#521).
+- The explain contract records proposed topic checks and related live reads
+  (#493), the CHR-grounded context submission matrix (#574), and import
+  verbose dry-run behavior (#520). These are design/grounding evidence;
+  `--context`, topic checks and contextual reads are not shipped CLI options.
 - Releases are one dispatch from `main` (#484, #485). `@next` publishes
   `X.Y.Z-next.<run_number>` with no commit, PR or tag, and reuses main's QA
   run on the commit instead of sweeping every channel again. `@latest` creates

package/README.md

@@ -4,21 +4,21 @@
 CLI (with an MCP server; TUI and HTTP proxy frontends planned) for talking to
 MikroTik RouterOS devices through a regularized, validated interface.
 
-Preview builds are published on npm. To try the current offline analyzer without
-installing centrs or connecting to a router:
+Stable releases are published on npm under `latest`. To try the offline
+analyzer without installing centrs or connecting to a router:
 
 ```bash
-bunx @tikoci/centrs@next explain '/ip/address print' --json
+bunx @tikoci/centrs@latest explain '/ip/address print' --json
 ```
 
-Use `bunx @tikoci/centrs@next --help` to inspect the full preview CLI, and
-`bunx @tikoci/centrs@next --version` (`-V`; `--json` for an envelope) to print
+Use `bunx @tikoci/centrs@latest --help` to inspect the release CLI, and
+`bunx @tikoci/centrs@latest --version` (`-V`; `--json` for an envelope) to print
 the exact version for scripts and field reports. The dist-tag follows standard
-SemVer semantics: a plain version (`0.1.8`) publishes to `latest` and carries
-`next` forward with it, while a `next` build (`0.1.9-next.23`) publishes to
+SemVer semantics: a plain version (`0.1.9`) publishes to `latest` and carries
+`next` forward with it, while a `next` build (`0.1.10-next.23`) publishes to
 `next` only and never moves `latest`. A `next` build is described by the
-`## 0.1.9 — next` section of [`CHANGELOG.md`](CHANGELOG.md). So `@next` is the
-leading edge and can equal `@latest` between cuts —
+next version's `## X.Y.Z — next` section of [`CHANGELOG.md`](CHANGELOG.md).
+So `@next` is the leading edge and can equal `@latest` between cuts —
 `npm view @tikoci/centrs dist-tags` is the authority.
 
 The full flag reference for every command is generated from the CLI metadata
@@ -63,7 +63,7 @@ product; without them this would just be a worse `curl`.
 | Command    | Purpose |
 | ---------- | ------- |
 | `retrieve` | Read RouterOS state over REST/native API. `--follow` keeps a menu's rows current over native API (snapshot, then a line per change; NDJSON); `--sample <interval>` re-reads it on a timer for counters; `--query` filters on the router with the `print where` grammar; `--wait` retries until a read succeeds (or an optional `--until` condition holds), up to a deadline. SNMP OID/MIB reads are planned. |
-| `execute`  | Run RouterOS CLI-shaped read/write commands (add/set/remove) over native API/REST/L2 surfaces. |
+| `execute`  | Run RouterOS CLI-shaped read/write commands (add/set/remove) over native API, REST, SSH or MAC-Telnet. |
 | `api`      | Structured RouterOS API passthrough (gh-api style): one command per operation, structured in/out, can write, over REST or native API. Follow changes with `api … <menu>/listen`; `--stream` streams any command's replies (native API; NDJSON). |
 | `terminal` | Open an interactive console, primarily SSH or MAC-Telnet. |
 | `transfer` | Upload, download and manage device files over REST/native API or SFTP; `upload` and `download` are shortcuts. |
@@ -96,7 +96,9 @@ stores:
   comment carries `identity=edge1`. Every other comment token stays inert prose.
   See `commands/devices/README.md` (Identity model) for the full resolution rules.
 - **`user` / `password`** — the credentials centrs connects with. They stay in
-  the CDB and are redacted from MCP results/resources.
+  the CDB. `devices show` / `add` / `set` withhold the password and report
+  `passwordSet` (`--show-password` reveals it); MCP results/resources always
+  redact it.
 - **`group`, `profile`, `session`, port** — used as-is.
 
 So `centrs retrieve edge1 /ip/address` works with no flags: `edge1` is looked
@@ -223,8 +225,8 @@ GitHub issues it links are the roadmap.
 
 Requirements:
 
-- Bun 1.3.11 or newer (CI runs the `packageManager` version in `package.json`;
-  Bun 2.x not yet validated).
+- Bun 1.4.4 or newer within 1.x (`engines.bun`: `>=1.4.4 <2`; CI runs the
+  `packageManager` version in `package.json`; Bun 2.x not yet validated).
 - Git.
 - `uv`, only for `bun run lint:actions` (zizmor workflow audit).
 - For integration tests: QEMU plus `@tikoci/quickchr` (handles CHR image

package/commands/devices/README.md

@@ -310,32 +310,27 @@ is no group-definition record. A group is the set of all entries whose
 `group` value matches by exact, case-sensitive string compare. An entry with
 `group=""` belongs to no group.
 
-`--group <G>` on any command resolves to the membership set and fans out.
+`--group <G>` on a router-facing fan-out command resolves to the membership set.
 `discover --save` writes MNDP records with `group=discovered`
 unless the caller supplies another group.
 
 ### Promotion (discovered → managed)
 
 There is no `promote` verb. Moving one device out of `group=discovered` and
-giving it credentials is `devices set <t> --new-group prod --user … --password
-…`. A **bulk** promotion (a whole discovered class at once) is the same call with
-a target selector picking the records:
+giving it credentials uses `set` on that target:
 
 ```bash
-devices set --group discovered --new-group prod \
-  --user admin --password … --force
+centrs devices set <target> --group prod --user admin --password …
 ```
 
-`--group` (and `--where`/`--all`/positionals) always **selects** which records to
-modify; `--new-group` always **writes** the group field. The two are distinct
-flags, so there is no select-vs-set overload — this resolves the former wrinkle.
-(Code follow-up: the CLI still overloads `--group` as the `add`/`set` field
-setter today; `examples.md` reflects that current flag until the `--new-group`
-split lands.)
+On `devices add`/`set`, `--group` writes the first-class group field; on
+`devices list` it filters. Bulk `set`/`remove` selection and a separate
+`--new-group` flag remain designed, not implemented. Both mutations currently
+require one target, with `--match` to disambiguate saved records.
 
 ## Fanout (multi-target invocations)
 
-Any command may receive multiple positional targets, one or more `--group`
+Router-facing fan-out commands may receive multiple positional targets, one or more `--group`
 flags, `--all`, `--default`, `--where <attr>=<value>` (device-class), and/or the
 geo selectors `--near <lat>,<lon>,<radius>` / `--bbox <south>,<west>,<north>,<east>`
 (see "Geo query" above) — see `docs/CONSTITUTION.md` (Target selection grammar).
@@ -365,21 +360,24 @@ centrs devices encrypt [--no-backup]    # explicitly encrypt an existing open CD
 centrs devices list [--group G] [--where attr=value]
                     [--near lat,lon,radius] [--bbox south,west,north,east]
                     [--format json|yaml|text]
-centrs devices show <target> [--explain] [--via <protocol>] [--match <type>]
+centrs devices show <target> [--explain] [--via <protocol>] [--match <selector>]
+                    [--show-password]
 centrs devices groups [--members]
-centrs devices discover [--timeout 15s] [--group G]      # = discover --save (save implied)
-centrs devices add <target> [--user U] [--password P] [--new-group G]
+centrs devices discover [--timeout 15s] [--group G]      # designed, not implemented; use `centrs discover --save`
+centrs devices add <target> [--user U] [--password P|--password-stdin] [--group G]
                              [--profile P|--profile-none|--profile-own]
                              [--session S] [--comment "text k=v"]
                              [--record-type ipAdmin|ipUser|macTarget|...]
                              [--gps lat,lon[,altitude[,altitude-type]]]
                              [--lat D] [--lon D] [--altitude M] [--altitude-type MSL|AGL]
-centrs devices set  <selector…> [--user U] [--password P] [--new-group G]
+                             [--show-password]
+centrs devices set  <target> [--match <selector>] [--user U] [--password P|--password-stdin] [--group G]
                              [--profile P|--profile-none|--profile-own]
                              [--session S] [k=v ...]
                              [--gps lat,lon[,altitude[,altitude-type]]]
                              [--lat D] [--lon D] [--altitude M] [--altitude-type MSL|AGL]
-centrs devices remove <selector…>
+                             [--show-password]
+centrs devices remove <target> [--match <selector>]
 centrs devices edit <target>            # future: clack/TUI wizard
 ```
 
@@ -423,18 +421,79 @@ is no `update`.
   existing `(target, user)` it errors `cdb/already-exists` unless `--force`
   overwrites; the same `target` under a *different* `--user` is a new record,
   not a collision.
-- `set` modifies existing record(s). First-class fields change via flags
-  (`--user`, `--password`, `--new-group`, `--profile[-none|-own]`, `--session`);
-  comment lookup/override keys change via `k=v` positionals. **Which** records to
-  modify is the target selector — positionals, `--group`, `--where`, `--all`
-  (constitution: target selection) — so `--group` here *selects* and
-  `--new-group` *writes* the group field (no overload). Against a missing target
-  it errors `cdb/not-found-target`; a multi-record `set` needs `--force`. Writing
+- `set` modifies one matched record. First-class fields change via flags
+  (`--user`, `--password`, `--group`, `--profile[-none|-own]`, `--session`);
+  comment lookup/override keys change via `k=v` positionals. The positional
+  target and optional `--match` select the record. Against a missing target
+  it errors `cdb/not-found-target`. Writing
   a first-class field name as a `k=v` positional (e.g. `user=x`) stays refused
   with `cdb/reserved-key` — the flag is the only path. Unknown comment keys warn
   (`cdb/unknown-option`), or error under `--strict`.
-- `remove` (aliases `rm`, `delete`) removes a single entry. Group-wide deletes
-  (`--group G`) require `--force` (writes are large).
+- `remove` (aliases `rm`, `delete`) removes one matched entry. The positional
+  target and optional `--match` select the record; group-wide deletion is not
+  implemented.
+
+### Record password channels
+
+`add` and `set` take the record password one of two ways:
+
+- `--password <secret>` — argv. Simple, but `ps` can show the value while the
+  process runs, and shell history can keep the command after it exits.
+- `--password-stdin` — read from stdin, so the value never appears in argv. For
+  automation and harnesses that spawn centrs (`printf '%s' "$PW" | centrs
+  devices set <t> --password-stdin`, or `centrs devices set <t>
+  --password-stdin < pw.txt`).
+
+`--password-stdin` rules:
+
+- Exactly one trailing newline (`\n` or `\r\n`) is stripped, so `echo pw |`
+  works. Any other whitespace is part of the password.
+- The rest must be valid UTF-8 with no leading byte-order mark; otherwise it
+  is `input/invalid-stdin`. The CDB stores record strings as UTF-8 and drops a
+  leading BOM on read, so either would store a different credential than the
+  bytes piped in.
+- Empty input (nothing, or only that one newline) is `input/empty-stdin`.
+  Clearing a stored password stays a deliberate `--password ""`, never an empty
+  pipe.
+- A terminal on stdin is refused with `usage/stdin-is-tty`; centrs does not
+  prompt.
+- `--password` together with `--password-stdin` is `usage/conflicting-flags`.
+  There is no precedence order between them.
+- Only `add` and `set` accept it; every other subcommand refuses it with
+  `input/invalid-command`.
+- The value is never echoed in errors. Success envelopes are the same as with
+  `--password`.
+
+There is no environment-variable channel for the record password:
+`CENTRS_PASSWORD` is the dial credential, not a CDB field.
+
+### Record password in output
+
+`show`, `add` and `set` withhold the stored record password by default, in text
+and JSON (#551). Each entry always carries `passwordSet: boolean` (true when a
+non-empty password is stored); text prints `password: (set, hidden)` or
+`(not set)`. `--show-password` returns the cleartext `password` on those three
+subcommands; every other subcommand refuses it with `input/invalid-command`.
+The `--explain` record's password field reads `<redacted>` without the flag.
+When an unknown-tcode `rawTail` comes before any decoded password field, the
+tail may hold the password, so without the flag its `value` reads
+`<redacted: N bytes, may contain password>` instead of the bytes. Such a
+record decodes to an empty password, so `passwordSet` is `false` (it reports
+the password centrs decoded and would dial with); the `cdb/unknown-field`
+warning then carries `context.mayContainPassword: true`.
+There is no encryption gate: the opt-in works the same on an open or encrypted
+CDB. `passwordSet` is not the WinBox `savedPassword` ("keep password") flag.
+
+The library matches the CLI: exported `showDevice` / `addDevice` / `setDevice`
+redact by default and take `showPassword?: boolean` (default `false`); with
+`showPassword: true` the entry type is `DevicesShowItemWithPassword`. MCP
+(`centrs_devices`) never passes it, so MCP output never carries the password.
+
+Dialing does not read this envelope. The resolver and the MCP allowlist gate
+read the raw record through an internal lookup (`lookupDeviceRecord`, not
+exported from the package root), so a CDB-credentialed dial still sends the
+stored password. The public entry type has no `password` field, so a caller
+that reached for the envelope instead fails to type-check.
 
 `--profile <name>` sets a named WinBox profile; `--profile-none` /
 `--profile-own` write the WinBox sentinels `<none>` / `<own>`. `profile` and
@@ -498,7 +557,9 @@ be recovered.
 `init` and `encrypt` act on the CDB file, not on records: they accept only
 `--cdb-file`, `--cdb-password`, `--format`/`--json`, plus `--encrypt` (`init`)
 or `--no-backup` (`encrypt`). Any other flag is `input/invalid-command`
-instead of being silently ignored.
+instead of being silently ignored. `devices init --help` and
+`devices encrypt --help` show only those accepted flags; the same metadata
+generates their sections in [`docs/CLI.md`](../../docs/CLI.md).
 
 Close WinBox and other CDB writers before conversion. If they share this path,
 they must reopen it using the CDB password; a stale writer can overwrite the

package/commands/devices/examples.md

@@ -94,7 +94,8 @@ centrs devices show 192.0.2.5 --cdb-file $CDB --explain
 ```
 
 `data.record` is the raw `WinBoxCdbRecord` (tag/marker/tcode/value). Useful
-for diagnosing unknown-field preservation.
+for diagnosing unknown-field preservation. The password field value reads
+`<redacted>` unless `--show-password` is passed (example 60).
 
 ## groups
 
@@ -720,3 +721,113 @@ A fresh path, so it does not depend on example 57 having already converted
 is retained, so
 `cdb/plaintext-backups` still warns. Test: `centrs devices encryption (#558)`
 in `test/integration/devices.test.ts`.
+
+## Record password in output
+
+`show`, `add` and `set` withhold the stored record password by default, in text
+and JSON and in the library envelopes (#551). Every entry carries
+`passwordSet: boolean`; `--show-password` (library: `showPassword: true`) opts in.
+`passwordSet` is not the WinBox `savedPassword` flag. MCP never returns the
+password and has no opt-in.
+
+### 60. `show` withholds the password and reports `passwordSet`
+
+```bash
+centrs devices show 192.0.2.5 --cdb-file $CDB --explain --json
+centrs devices show 192.0.2.5 --cdb-file $CDB
+```
+
+`data.entry` has `passwordSet: true` and no `password` key. The `--explain`
+record's password field (tag 3) reads `<redacted>`. Text prints
+`password:      (set, hidden)`, or `(not set)` for an empty password.
+
+### 61. `--show-password` returns the password on `show`, `add` and `set`
+
+```bash
+centrs devices show 192.0.2.5 --cdb-file $CDB --show-password --json
+centrs devices add 198.51.100.57 --user writer --password pw57 --cdb-file $CDB --json
+centrs devices set 198.51.100.57 --group lab --cdb-file $CDB --show-password --json
+```
+
+`show` returns `data.entry.password: "secret"`. The `add` without the flag
+returns `passwordSet: true` and no `password`; the `set` with it returns
+`data.entry.password: "pw57"`.
+
+### 62. `--show-password` is refused outside `show` / `add` / `set`
+
+```bash
+centrs devices list --cdb-file $CDB --show-password --json
+```
+
+`input/invalid-command` with `error.context: { subcommand: "list", flag:
+"--show-password" }`, the same refusal other subcommand-scoped flags use.
+
+## Record password on stdin
+
+`--password-stdin` (#582) reads the record password from fd 0 so it never rides
+argv. These run as subprocesses (`test/integration/cli-process.ts`), because
+only a child process can be handed real stdin bytes. The newline, empty and TTY
+rules are also unit-tested in `test/unit/devices-password-stdin.test.ts`.
+
+### 63. `add --password-stdin` stores the piped value
+
+```bash
+printf 'piped pw\n' | centrs devices add 192.0.2.77 --user robot --password-stdin --cdb-file $CDB --json
+```
+
+`ok: true`. The stored password is `piped pw`: one trailing newline is
+stripped, the inner space is kept.
+
+### 64. `set --password-stdin` strips a trailing CRLF
+
+```bash
+printf 'rotated\r\n' | centrs devices set 192.0.2.5 --password-stdin --cdb-file $CDB --json
+```
+
+`ok: true`. The stored password is `rotated`; group and comment are unchanged.
+
+### 65. Empty stdin is refused
+
+```bash
+printf '' | centrs devices set 192.0.2.5 --password-stdin --cdb-file $CDB --json
+```
+
+Errors with `input/empty-stdin` (also for a lone `\n`). The CDB is not written
+and no backup is made.
+
+### 66. `--password` with `--password-stdin` conflicts
+
+```bash
+echo stdin-secret | centrs devices set 192.0.2.5 --password argv-secret --password-stdin --cdb-file $CDB --json
+echo stdin-secret | centrs devices set 192.0.2.5 --password --password-stdin --cdb-file $CDB --json
+```
+
+Both error with `usage/conflicting-flags`. Neither value appears in the error;
+`--password` cannot consume `--password-stdin` as a literal credential.
+
+### 67. Non-UTF-8 or BOM-prefixed stdin is refused
+
+```bash
+printf 'pw\377\n' | centrs devices set 192.0.2.5 --password-stdin --cdb-file $CDB --json
+printf '\357\273\277pw\n' | centrs devices set 192.0.2.5 --password-stdin --cdb-file $CDB --json
+```
+
+Both error with `input/invalid-stdin`: the first is not valid UTF-8, the second
+starts with a byte-order mark. The bytes are not echoed, the CDB is not written
+and no backup is made.
+
+## File-command help
+
+### 68. `init` and `encrypt` show only their accepted flags
+
+```bash
+centrs devices init --help
+centrs devices encrypt --help
+```
+
+Both exit 0 without reading or writing a CDB. Each shows its own usage, the
+CDB path/password and output flags, plus `--encrypt` for `init` or
+`--no-backup` for `encrypt`. Record and selection flags are absent, including
+`--user`, `--password-stdin`, `--show-password`, `--group` and `--match`.
+Test: `devices file-command help is scoped without opening a CDB` in
+`test/integration/cli-smoke.test.ts` (network-free).

package/commands/execute/README.md

@@ -146,8 +146,8 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   all-strings). Unlike `jo`-style KV builders, there is no per-value
   type-forcing escape, because the device, not centrs, owns value typing.
 - On an empty-CDB resolution failure, execute (like retrieve) emits the
-  `tip/no-devices` tip, steering toward `centrs devices discover` /
-  `centrs settings`.
+  `tip/no-devices` tip, steering toward `centrs discover --save` /
+  `centrs devices add`.
 - Protocol surfaces are native API, REST, mac-telnet, and SSH. RoMON and
   WinBox Terminal are later. SNMP is retrieve-only and must reject execute.
 - For a MAC target not resolved from CDB, auto-selection defaults to

package/commands/retrieve/README.md

@@ -583,5 +583,5 @@ reach green is forbidden. See `docs/CONSTITUTION.md` for the full done rule.
 - **ssh / mac-telnet / romon / winbox-terminal** — execute surfaces, not
   retrieve surfaces.
 - **tips** — when a `<router>` fails to resolve against an empty CDB, retrieve
-  emits the same `tip/no-devices` advice as `devices list`, steering toward
-  `centrs devices discover` and `centrs settings`.
+  emits `tip/no-devices`, steering toward `centrs discover --save` and
+  `centrs devices add`.

package/commands/settings/README.md

@@ -156,6 +156,12 @@ centrs settings reset [<attr>]                 # clear one/all back to built-in
   elsewhere (`src/cli/api.ts`'s `exitCode`), never a bare non-zero without an
   envelope. `settings` has no fan-out surface, so the constitution's `2`
   ("partial" fan-out result) never applies here.
+- **`get` output:** text mode renders the one entry exactly as `print`
+  renders that key — `key: value [source: kind (key)]` under the canonical
+  attr name, plus any `Tips:` footer (examples.md #33). `get`'s `data` is the
+  bare `{ source, value }` entry, so the JSON/YAML envelope names the key in
+  `meta.operation.attr` (canonical name, whichever spelling was asked for).
+  A blank `<attr>` is refused at parse time as `input/invalid-command`.
 - **Agent-facing:** every subcommand emits the standard envelope
   (`ok`/`data`/`meta`/`error`) regardless of TTY — `--format json` is
   honored on `settings` itself exactly like every other command, so an agent

package/commands/settings/examples.md

@@ -406,3 +406,20 @@ XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings print --cdb-file /tmp/does-not-exi
 device configured" rather than `cdb/not-found`, since reporting settings
 should not require a CDB to exist at all). `data.defaultDevice = {
 configured: false }`.
+
+## Text output
+
+### 33. Get renders one entry in text mode, like print
+
+```bash
+XDG_CONFIG_HOME=$SETTINGS_DIR CENTRS_MAX_RESULTS=7 centrs settings get CENTRS_MAX_RESULTS
+XDG_CONFIG_HOME=$SETTINGS_DIR centrs settings get ssh-key
+```
+
+`ok: true`, exit 0. Text mode prints the single entry as one line in the
+same `key: value [source: kind (key)]` format `print` uses, under the
+canonical attr name whichever spelling was asked for: `max-results: 7
+[source: env (CENTRS_MAX_RESULTS)]`, then `ssh-key: (unset) [source:
+default (ssh-key)]` followed by its `Tips:` footer. `get`'s `data` is the bare
+entry, so the JSON envelope names the key in `meta.operation.attr`. A
+credential-shaped key renders `(redacted)`, never the secret.

package/docs/CLI.md

@@ -11,7 +11,7 @@ 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. |
+| [`execute`](#execute) | Run a RouterOS read or write command via native API, REST, SSH, 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). |
@@ -71,7 +71,7 @@ Usage: centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <targe
 
 ## execute
 
-Run a RouterOS read or write command via native API, REST, or mac-telnet.
+Run a RouterOS read or write command via native API, REST, SSH, or mac-telnet.
 
 ```text
 Usage: centrs execute <target> <command> [flags] | centrs execute <target...> -- <command> [flags] | centrs execute --host <host|url> [--] <command> [flags] | centrs execute --group <name> <command> [flags]
@@ -79,7 +79,7 @@ Usage: centrs execute <target> <command> [flags] | centrs execute <target...> --
 
 | 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. |
+| `--via` | &lt;native-api\|rest-api\|ssh\|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. |
@@ -101,7 +101,7 @@ Usage: centrs execute <target> <command> [flags] | centrs execute <target...> --
 | `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--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). |
+| `--validate / --no-validate` |  | Run offline analysis, then RouterOS :parse, plus `/console/inspect` for structured commands over native API/REST (default true; `--validate=false` disables both stages). |
 | `--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. |
@@ -150,7 +150,7 @@ Usage: centrs api <router> <endpoint> [flags] | centrs api --host <host|url> <en
 | `--match` | &lt;user=name\|target=addr\|record-type&gt; | Pick one of several CDB records saved for `<router>` (as `devices show --match`); single target only. |
 | `--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). |
+| `--validate / --no-validate` |  | Validate structured requests with `/console/inspect`; `/execute` scripts run offline analysis, then RouterOS :parse (default true; `--validate=false` disables both stages). |
 | `--format` | &lt;json\|ndjson\|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, on stderr. |
@@ -271,17 +271,19 @@ Usage: centrs devices <init|encrypt|list|show|groups|add|edit|set|remove> [args]
 | `--encrypt` |  | `init` only — require encrypted creation with a non-empty CDB password; refuse an existing open CDB. |
 | `--no-backup` |  | `encrypt` only — skip the plaintext pre-conversion snapshot. Without that snapshot, a forgotten password cannot be recovered. |
 | `--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 for `init --encrypt`, `encrypt`, and to re-encrypt on writes. |
+| `--cdb-password` | `<secret>` | CDB password for encrypted reads, writes, explicit encrypted initialization and conversion. Falls back to `CENTRS_CDB_PASSWORD`; a password alone never converts an open CDB. |
 | `--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. |
+| `--group` | `<name>` | `list` filter / `add`,`set` 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. |
+| `--explain` |  | `show` only — include the raw `WinBoxCdbRecord` in `data.record` (its password field reads `<redacted>` unless `--show-password`). |
+| `--match` | &lt;user=…\|target=…\|record-type&gt; | `show`,`set`,`remove` — 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. |
+| `--password-stdin` |  | `add`,`set` — read the record password from stdin (one trailing newline stripped) so it never rides argv. Conflicts with `--password`. |
+| `--show-password` |  | `show`,`add`,`set` — include the record password in cleartext. By default output carries `passwordSet` and withholds the password. |
 | `--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. |
@@ -298,6 +300,38 @@ Usage: centrs devices <init|encrypt|list|show|groups|add|edit|set|remove> [args]
 | `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
 | `--json` |  | Shortcut for `--format json`. |
 
+### devices init
+
+Create an empty CDB at the resolved path; existing readable files are left unchanged.
+
+```text
+Usage: centrs devices init [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--encrypt` |  | `init` only — require encrypted creation with a non-empty CDB password; refuse an existing open CDB. |
+| `--cdb-file` | `<path>` | Override the resolved CDB path (default `~/.config/tikoci/winbox.cdb`). |
+| `--cdb-password` | `<secret>` | CDB password for encrypted reads, writes, explicit encrypted initialization and conversion. Falls back to `CENTRS_CDB_PASSWORD`; a password alone never converts an open CDB. |
+| `--format` | &lt;text\|json\|yaml&gt; | Output format for the CLI response. |
+| `--json` |  | Shortcut for `--format json`. |
+
+### devices encrypt
+
+Encrypt an existing CDB in place, or verify an already-encrypted file; existing backups remain unchanged.
+
+```text
+Usage: centrs devices encrypt [flags]
+```
+
+| Flag | Value | Description |
+| ---- | ----- | ----------- |
+| `--no-backup` |  | `encrypt` only — skip the plaintext pre-conversion snapshot. Without that snapshot, a forgotten password cannot be recovered. |
+| `--cdb-file` | `<path>` | Override the resolved CDB path (default `~/.config/tikoci/winbox.cdb`). |
+| `--cdb-password` | `<secret>` | CDB password for encrypted reads, writes, explicit encrypted initialization and conversion. Falls back to `CENTRS_CDB_PASSWORD`; a password alone never converts an open CDB. |
+| `--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.