@tikoci/centrs 0.1.7 → 0.1.8

package/commands/api/README.md

@@ -7,17 +7,19 @@ single REST or native-API operation, and returns the result in the standard
 envelope.
 
 Status: `CHR-passed` over `rest-api` and `native-api`, including multi-target
-fan-out and open-ended `--stream` follow (native-api only), per
+fan-out and incremental `--stream` replies (native-api only), per
 `docs/MATRIX.md`. This file describes intent and flags; the matrix holds the
 cell states. Load-bearing rules — envelope, errors, settings precedence,
 identity, validation, protocol selection — live in
 [`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md); the `(constitution: …)`
 notes below point there rather than restating them.
 
-`api` absorbs the former `stream` command: open-ended follow is `api <router>
-<endpoint> --stream` (or the `/listen` endpoint form). `--listen` is an accepted
-alias of `--stream`. Streaming is single-session — it cannot combine with
-multi-target fan-out (see below).
+`api` absorbs the former `stream` command. `api` sends the command as typed:
+following changes is the menu's own `listen` (`api <router> ip/address/listen`),
+and `--stream` delivers any command's replies incrementally. `--listen` was
+removed in #402 (`usage/removed-flag`, naming the exact replacement): it also
+turned a GET into a listen. Streaming is single-session — it cannot combine
+with multi-target fan-out (see below).
 
 ## Where `api` sits — the verb trichotomy
 
@@ -46,8 +48,10 @@ centrs api <router> <endpoint> [flags]
 - `<endpoint>` — a REST-style path, leniently normalized. All of
   `ip/address`, `/ip/address`, `rest/ip/address`, `/rest/ip/address`,
   `"ip address"`, `'ip address'` canonicalize to `/ip/address`. A trailing id
-  segment (`ip/address/*1`) addresses one row. A trailing `/listen` segment
-  infers `--stream` + `--via native-api`.
+  segment (`ip/address/*1`) addresses one row for GET/PATCH/DELETE; PUT and
+  POST reject it with `input/invalid-path`. A trailing `/listen` segment is
+  the menu's `listen` command, which implies `--stream` + `--via native-api`
+  and requires GET (`ip/address/*1/listen` follows one row).
 
 The HTTP method (`-X`, default `GET`) is honored **literally** against RouterOS's
 REST mapping — `GET`→print/get, **`PUT`→add**, `PATCH`→set, `DELETE`→remove,
@@ -64,18 +68,31 @@ the generated reference cannot carry:
 
 - `-f` values pass through verbatim (no type-guessing); `-d`/`--input`
   collide with `-f` → `usage/conflicting-flags`.
-- `--query`/`--filter` map to REST `.query` words / native `?` words.
+- `--query`/`--filter` take the same `print where` grammar as
+  `retrieve --query` ([retrieve README → Query](../retrieve/README.md#query---query))
+  and compile to REST `.query` words / native `?` words. A bare name is
+  `name=yes` for a boolean and "has a value" otherwise, which the router is
+  asked during validation; with `--validate=false` (or `--raw`) a bare name
+  fails `input/invalid-query`. Unlike `retrieve`, `api` does not check the
+  property names.
 - `--raw-query` is emitted as-is; the caller owns the stack — e.g.
-  `--raw-query type=ether --raw-query type=vlan --raw-query '#|'` (OR).
+  `--raw-query type=ether --raw-query type=vlan --raw-query '#|'` (OR), or the
+  has-property `--raw-query comment` / absence `--raw-query -comment` words.
 - `--via rest-api --stream` errors `transport/capability-unsupported`
   (REST's 60 s cap cannot follow).
-- Under `--stream`, `--format json`/`yaml` emit one compact envelope per
-  line (NDJSON); `text` emits a concise row per frame.
+- `--format ndjson` prints every envelope as one compact line, one-shot or
+  streamed; it never starts a stream by itself. Under `--stream`,
+  `json`/`yaml` also emit NDJSON (unchanged for existing callers); `text`
+  emits a concise row per frame.
 - The target/auth flags (`--host`, `--port`, `--username`, `--password`,
   `--insecure`, `--timeout`, `--cdb-file`, `--cdb-password`, `--resolve`)
   use the same single-target resolver as `retrieve`/`execute`; `--quickchr`
   resolves host/port/auth from the live `@tikoci/quickchr` descriptor
   instead (constitution: resolution providers).
+- The `--host` **flag** stands in for a missing `<router>`:
+  `api --host http://192.0.2.10:8080 system/resource` targets that host with
+  no CDB lookup. `CENTRS_HOST` never does; `api <endpoint>` with it set is
+  still a missing `<router>`.
 
 ## Fan-out (multi-target)
 
@@ -93,7 +110,7 @@ vs `--query` distinction.
 - **Writes fan out under `--yes`**, confirmed once up front (not per target).
   Without `--yes`, the error names the blast radius (how many routers) and that
   `--yes` is required.
-- **`--listen`/`--stream` is single-session** → `usage/fanout-not-supported` in
+- **`--stream` (or a `/listen` endpoint) is single-session** → `usage/fanout-not-supported` in
   fan-out mode. **`--raw` strips the envelope** → `usage/conflicting-flags` in
   fan-out mode (per-target envelopes can't be bare).
 
@@ -171,35 +188,100 @@ the RouterOS error payload to stderr with a nonzero exit; a centrs-side failure
 with no RouterOS response prints a compact `{code,message}` to stderr. Exit code is
 `0` iff `ok`.
 
-## Multi-frame results: bounded vs open-ended
-
-RouterOS produces multi-frame output two ways, and `api` treats them differently:
-
-- **Bounded `duration=` / `monitor` commands are ordinary `api` calls.** Both
-  transports return the accumulated frames as a normal **array** (REST regularizes
-  the native `!re` frames into `.section`-keyed records; native's reader collects
-  them until the command completes). No flag needed — e.g.
-  `centrs api $R interface/monitor-traffic -f interface=ether1 -f duration=5s`
-  returns a `.section` array. REST bounds these at the **60 s** cap (a longer
-  `duration=` terminates early with an error); native has no cap. This is **not**
-  NDJSON.
-- **Open-ended follow is `--stream` (alias `--listen`), native-api only.** Only
-  the native API `/listen` command follows indefinitely (REST cannot — the 60 s
-  cap). Each `!re` becomes one rest-style envelope frame (one NDJSON line; a
-  deletion's `.dead=true` flag is preserved); the stream ends with a summary
-  envelope (`data.stopReason` ∈ `count-reached`/`duration-elapsed`/`interrupted`/
-  `transport-error`, plus `frames` and `durationMs`). `--duration`/`--count`
-  bound it; Ctrl-C stops and still emits the summary. The `--duration` window
-  starts once validation is done, so it excludes validation (and the connect and
-  login validation needs). With `--no-validate`, connect and login happen inside
-  the window. Stopping on `--duration` or Ctrl-C sends RouterOS `/cancel`, and
-  centrs waits up to `--timeout` for the router to acknowledge it. A router that
-  never does gets its session closed locally, and the summary carries a
-  `transport/cancel-unacknowledged` warning (#385). Reaching `--count` sends
-  `/cancel` best-effort and closes the session without waiting, so it never
-  carries that warning (examples L5). `--via rest-api --stream` →
-  `transport/capability-unsupported`. The exit code reflects whether the stream
-  *started* cleanly, not whether every frame was `ok`.
+## Multi-frame results and incremental replies
+
+Without `--stream`, bounded commands return their accumulated rows as an ordinary
+array. REST retains its **60 s** cap; native API collects replies until `!done`.
+
+`--stream` emits the literal command's native replies incrementally, whether
+the command is finite or open-ended (#402: one wire reply, one line).
+`--via rest-api --stream` fails with `transport/capability-unsupported`;
+centrs never substitutes polling.
+
+- **Following changes is a command you ask for**: the `<menu>/listen`
+  endpoint (GET; implies `--stream` and native-api), or POST `<menu>/print`
+  with `-f follow-only=` / `-f follow=` to pass print arguments.
+  `ip/address/*1/listen` follows one row (`?.id=*1`).
+- **GET menu + `--stream`** streams one literal print and completes; it does
+  not follow. Its summary carries `tip/stream-print` naming the `/listen`
+  form (see the notice below). A streamed GET (or a `/listen`) rejects `-f` fields rather than
+  silently dropping them.
+- **POST command + `--stream`** runs the literal command with its attributes:
+  `api $R /tool/ping -X POST -f address=10.0.2.2 -f count=3 --stream --yes`.
+  POST `/system/resource/print -f interval=1 --stream --count 2` samples twice.
+  PUT/PATCH/DELETE retain their add/set/remove mapping and confirmation gates.
+  Query/projection flags on these mutations or `/execute` scripts fail with
+  `usage/conflicting-flags` instead of being ignored. `/execute` retains
+  synchronous `as-string` script semantics. Streaming never makes a command
+  read-only.
+- Each wire reply emits one envelope with `meta.operation.stream.kind=frame`
+  and `reply`: **`re`** (a row; `data` is the row, device `.section`,
+  `.dead`, `.nextid` and `.about` verbatim) or **`empty`** (RouterOS `!empty`:
+  zero rows; `data` is `null`). RouterOS sends `!empty` for an empty finite
+  read, for **each zero-row tick** of `print interval=`, and for a listen
+  cancelled before it sent anything. A frame received after centrs stopped the
+  stream locally carries `afterStop: true` — that cancellation `!empty` is not
+  evidence of an empty table. A terminal `!done` is not a frame: its
+  attributes, when received, appear in successful summary `data.done`,
+  including a terminal result received during local cancellation. The stop
+  reason still reports the first local bound.
+- Read outcomes from **`meta.operation.stream`** on both success and failure;
+  successful `data.stopReason` is a compatibility copy.
+- Exactly one terminal summary follows a started stream. Its marker is
+  `meta.operation.stream.kind=summary`, with `frames` (every reply line),
+  `rows` (`!re`), `empty` (`!empty`), `durationMs`, and `stopReason`:
+  `completed`, `count-reached`, `duration-elapsed`, `interrupted`,
+  `routeros-error`, or `transport-error`. `meta.operation.objectCount` is
+  `rows`. A RouterOS/transport failure (`!trap`, `!fatal`, a dropped
+  connection) has `ok:false` and a structured `error`; summary counts/reason
+  are in metadata (error envelopes have no `data`). Previously emitted rows
+  remain partial results. A failed summary retains any
+  `transport/cancel-unacknowledged` warning as well. Preflight failures emit
+  one error envelope without starting a stream.
+- Structured streams put **all** envelopes, including errors, on stdout as
+  NDJSON and exit nonzero for any failure, even after successful rows. Text
+  mode uses the same outcome/exit rules. `--raw` retains bare payloads and
+  stderr errors; it does not provide the structured stream contract.
+
+`api` never edits a change feed to make it safer; it says what RouterOS will
+not report as tips (CHR 7.23.7 + 7.24.5). Because that advice depends only on
+the request, it arrives **first**: a leading envelope with
+`meta.operation.stream.kind=notice`, `data: null` and the `tips`, before any
+reply — so a filtered watch that never gets a reply still shows it. A notice is
+not a reply and is not counted in `frames`/`rows`; a stream with no advice has
+no notice. The same tips are repeated on the terminal summary, successful or
+failed. `--raw` omits the notice.
+
+- `tip/filtered-follow` — a `listen` (or `follow`) with a query reports
+  neither rows leaving the filter nor deletes. Follow unfiltered and filter
+  on the client, or follow one row (`<menu>/*id/listen`). Stateful filtered
+  follow belongs to `retrieve --follow` (#396/#397).
+- `tip/follow-proplist` — a `--proplist` without `.id,.dead` makes RouterOS
+  strip both from a delete frame, even under `?.id=`: the delete arrives as an
+  `!re` with no attributes. Add `.id,.dead` to see deletes.
+
+`--count N` stops after N **`!re` rows**; `!empty` replies never count, so an
+empty tick cannot use up the count before the data arrives.
+`-f count=3` and `-f duration=2s` are **device arguments**; `--count` and
+`--duration` are **centrs bounds**. The duration window starts after validation,
+excluding its connection/login. With validation disabled, connect/login happen
+inside the window. Duration expiry or Ctrl-C sends `/cancel` and waits up to
+`--timeout` for acknowledgement; otherwise centrs closes locally and reports
+`transport/cancel-unacknowledged`. Count stop sends `/cancel` best-effort and
+closes without waiting (#385, example L5). A local bound is not a device `!done`.
+
+For the next wire change on a connected router:
+
+```bash
+centrs api $A /ip/address/listen --port $API_PORT --stream --count 1 --duration 60s
+```
+
+This counts replies rather than asserting readiness or a predicate. Use
+`retrieve --wait` / `--until` / `--until-empty` instead when the router may
+still be booting, when the condition may already be true, when you are on REST,
+or when the state you need is one that `listen` never reports (counters,
+`running`, timeouts)
+([retrieve → Wait](../retrieve/README.md#wait---wait---until---until-empty)).
 
 ## MCP (deferred — forward guidance)
 

package/commands/api/examples.md

@@ -5,7 +5,8 @@ Each numbered example is an executable spec asserted by CHR integration tests
 `test/integration/api.test.ts` (rest-api examples),
 `test/integration/api-native.test.ts` (native-api examples, N…),
 `test/integration/api-listen.test.ts` (streaming examples, L…), and
-`test/integration/api-fanout.test.ts` (fan-out examples, F…). If a line here is not
+`test/integration/api-fanout.test.ts` (fan-out examples, F…), and
+`test/integration/retrieve-query.test.ts` (query grammar examples, QA…). If a line here is not
 exercised by a test, the test file is wrong; if a line passes only with
 `--validate=false`, the implementation is wrong (see
 [`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md)).
@@ -199,10 +200,21 @@ command was rejected at run, not at validation. Ordinary output that merely
 mentions a fault string (`:put "status: no such item appears in help"`) stays
 `ok: true`.
 
-### 17. `--via rest-api --listen` is rejected
+### 16e. Wrong credentials: the device stage is not reached (GH#435)
 
 ```bash
-centrs api $R ip/address --listen --via rest-api --username $U --password $P
+centrs api $R system/identity --username centrs-wrong --password centrs-wrong --json
+```
+
+Envelope: `ok: false`, `error.code=transport/auth-failed`. `meta.validation`
+has no `result`. Its device stage is `skipped` with
+`reason: "not reached: transport/auth-failed"`, because RouterOS answered 401
+before `/console/inspect` could give a verdict.
+
+### 17. `--via rest-api --stream` is rejected
+
+```bash
+centrs api $R ip/address --stream --via rest-api --username $U --password $P
 ```
 
 Envelope: `ok: false`, `error.code=transport/capability-unsupported` (REST cannot
@@ -233,7 +245,7 @@ centrs api $R interface/monitor-traffic -X POST -f interface=ether1 -f duration=
 ```
 
 Envelope: `ok: true`, `data` is an **array** of `.section`-keyed records (one per
-~second), `meta.via=rest-api`. This is an ordinary bounded call — no `--listen`,
+~second), `meta.via=rest-api`. This is an ordinary bounded call — no `--stream`,
 no NDJSON. `monitor-traffic` is a command (not `print`/`get`), so it is a
 `POST` and write-classed (needs `--yes`); centrs never relaxes that to read-only.
 (REST bounds it at the 60 s cap; native has no cap.)
@@ -265,6 +277,15 @@ key. Contrast example 13, where bare `--raw` skips the preflight entirely. This
 pair is how you tell a RouterOS rejection from a centrs bug while staying on the
 bare-passthrough surface.
 
+### H1. `--host` stands in for `<router>` (#428)
+
+```bash
+centrs api --host $R system/identity --username $U --password $P --json
+```
+
+`ok: true`, with `data.name` the router's identity. The lone positional is the
+endpoint, and there is no CDB lookup.
+
 ## native-api (`--via native-api`)
 
 The same contract over the binary API. Validation still runs through
@@ -359,26 +380,29 @@ surface the `as-string` console text as `data`.
 
 ## listen / `--stream` (native-api only)
 
-Open-ended follow. `--stream` is the primary flag; `--listen` is an accepted
-alias and a trailing `/listen` endpoint segment infers it. Output is NDJSON: one
-envelope per change frame, then a terminating summary envelope.
+`api` sends the command as typed (#402). Following changes is the menu's
+`listen`, requested as a `<menu>/listen` endpoint, which implies `--stream` and
+native-api. `--stream` delivers any command's replies incrementally: one NDJSON
+envelope per wire reply (`!re` row or `!empty`), then a terminating summary.
+`--listen` is removed (`usage/removed-flag`, unit- and smoke-tested with its
+exact replacement).
 
-### L1. `--stream` streams a change as an NDJSON frame, then a summary
+### L1. A `/listen` stream emits a change as an NDJSON frame, then a summary
 
 ```bash
-centrs api $A ip/address --stream --count 1 --via native-api --port $API_PORT --username $U --password $P
+centrs api $A ip/address/listen --count 1 --via native-api --port $API_PORT --username $U --password $P
 ```
 
 While listening, the harness adds an address over REST. stdout is NDJSON: at least
-one envelope frame for the new row (`meta.operation.stream.kind=frame`), then a
-final summary envelope (`meta.operation.stream.kind=summary`,
-`data.stopReason=count-reached`, `data.frames>=1`). Exit code 0 (stream started
-cleanly).
+one envelope frame for the new row (`meta.operation.stream.kind=frame`,
+`reply=re`), then a final summary envelope (`meta.operation.stream.kind=summary`,
+`meta.operation.stream.stopReason=count-reached`,
+`meta.operation.stream.rows>=1`). Exit code 0 (successful local count stop).
 
 ### L2. A deletion frame carries `.dead`
 
 ```bash
-centrs api $A ip/address --stream --duration 3s --via native-api --port $API_PORT --username $U --password $P
+centrs api $A ip/address/listen --duration 3s --via native-api --port $API_PORT --username $U --password $P
 ```
 
 The harness removes a pre-seeded address; an emitted frame's record carries
@@ -397,11 +421,14 @@ No `--stream` / `--via` given; the `/listen` endpoint infers `--stream` and
 ### L4. Bounded `--duration` reports its stop reason
 
 ```bash
-centrs api $A ip/address --stream --duration 2s --via native-api --port $API_PORT --username $U --password $P
+centrs api $A ip/address/listen --duration 2s --via native-api --port $API_PORT --username $U --password $P
 ```
 
 With no change during the window, the stream ends after ~2 s with a summary
-envelope whose `data.stopReason=duration-elapsed`. Exit code 0.
+envelope whose `meta.operation.stream.stopReason=duration-elapsed`, `rows=0`,
+`empty=1`. Exit code 0. RouterOS answers the cancel of a listen that sent
+nothing with interrupted, `!empty`, `!done`: that `!empty` is the one frame,
+with `reply=empty`, `data=null` and `afterStop: true`.
 
 ### L5. A router that ignores `/cancel` cannot hold the process open
 
@@ -424,6 +451,145 @@ loopback native-API peer that ignores it, as a real CLI process:
 chatty peer, trap without `!done`, close after cancel) are in
 `test/unit/native-api.test.ts`.
 
+### L6. Finite ping completes naturally
+
+```bash
+centrs api $A tool/ping -X POST -f address=10.0.2.2 -f count=3 --stream --yes --via native-api --port $API_PORT --username $U --password $P
+```
+
+Three reply frames, then a successful summary with `meta.operation.stream.stopReason=completed`.
+The device's `count=3` completes the command; no centrs `--count` is needed.
+
+### L7. Monitor replies preserve `.section`
+
+```bash
+centrs api $A interface/monitor-traffic -X POST -f interface=ether1 -f duration=2s --stream --yes --via native-api --port $API_PORT --username $U --password $P
+```
+
+One or more rows carrying device `.section` values, then `completed`.
+
+### L8. Explicit print interval streams instead of listening
+
+```bash
+centrs api $A system/resource/print -X POST -f interval=1 --stream --count 2 --via native-api --port $API_PORT --username $U --password $P
+```
+
+Two reply frames and a `count-reached` summary. POST print stays read-only.
+
+### L9. Projection is sent as typed; the tip says what it hides
+
+```bash
+centrs api $A ip/address/listen --proplist address --duration 3s --via native-api --port $API_PORT --username $U --password $P
+centrs api $A ip/address/listen --proplist address,.id,.dead --duration 3s --via native-api --port $API_PORT --username $U --password $P
+```
+
+The harness deletes a seeded address during each. With `address` alone no
+frame carries `.dead` for it, and the leading notice and the summary carry
+`tip/follow-proplist`.
+With `address,.id,.dead` the delete frame is `{ ".id", ".dead": "true" }` and
+there is no tip.
+
+### L10. A filtered listen is sent as typed, with a tip
+
+```bash
+centrs api $A ip/address/listen --query interface=ether1 --duration 3s --via native-api --port $API_PORT --username $U --password $P
+```
+
+The harness deletes a seeded `ether1` address while listening. RouterOS sends
+nothing for it: the only frame is the cancellation `!empty` (`afterStop`).
+The first line is a `notice` with `tip/filtered-follow`; the summary is `ok`
+and repeats it. `--raw-query` is sent
+the same way.
+
+### L11. Command attributes are validated
+
+```bash
+centrs api $A tool/ping -X POST -f no-such-arg=x --stream --yes --via native-api --port $API_PORT --username $U --password $P
+```
+
+`validation/unknown-attribute`; no ping stream starts.
+
+### L12. Streaming keeps the mutator confirmation gate
+
+```bash
+centrs api $A system/license/renew -X POST --stream --via native-api --port $API_PORT --username $U --password $P
+```
+
+Non-interactively, `usage/confirmation-required`; no renew operation is sent.
+
+### L13. Mutation streams retain method mapping and terminal `ret`
+
+```bash
+centrs api $A ip/address -X PUT -f address=198.51.100.34/32 -f interface=ether1 --stream --yes --via native-api --port $API_PORT --username $U --password $P
+```
+
+A successful zero-row summary with `data.done.ret` naming the created address.
+The harness retrieves that ID to check its address, then streams DELETE on that
+ID and requires natural completion. Neither mutation becomes a listen.
+
+### L14. Streamed `/execute` runtime errors fail the terminal summary
+
+```bash
+centrs api $A execute -X POST --stream --via native-api --yes --json -f 'script=/ip/service/set www-ssl certificate=nope' --port $API_PORT --username $U --password $P
+```
+
+With validation enabled and no `nope` certificate, syntax validation passes but
+RouterOS rejects the value at runtime. The sole terminal envelope is `ok: false`,
+`routeros/invalid-value`, and `meta.operation.stream.stopReason=routeros-error`; the CLI exits nonzero.
+Ordinary stdout such as `:put "status: no such item appears in ordinary output"`
+still completes successfully with its text in `data.done.ret`.
+
+### L15. An addressed listen reports its deletion; a projection hides it
+
+```bash
+centrs api $A "ip/address/$ID/listen" --duration 3s --via native-api --port $API_PORT --username $U --password $P
+centrs api $A "ip/address/$ID/listen" --duration 3s --proplist address --via native-api --port $API_PORT --username $U --password $P
+```
+
+For each variant the harness seeds an address, starts the addressed listen
+(`?.id=$ID`), and deletes it after the listening barrier. Without projection
+the stream emits `.id=$ID` with `.dead=true` and no tip. With `--proplist
+address` RouterOS strips both, so the delete is one `!re` with no attributes
+(`data={}`) and the summary carries `tip/follow-proplist`.
+
+### L16. POST print preserves query/projection in either delivery mode
+
+```bash
+centrs api $A ip/address/print -X POST --query address=198.51.100.34/32 --proplist address --via native-api --port $API_PORT --username $U --password $P
+centrs api $A ip/address/print -X POST --query address=198.51.100.34/32 --proplist address --stream --via native-api --port $API_PORT --username $U --password $P
+```
+
+The harness seeds the L13 address. Both modes return only that address and only
+the requested `address` field; the streamed form then completes naturally. The
+one-shot REST equivalent is also checked, using the same query/projection.
+
+### L17. A GET stream is one literal print
+
+```bash
+centrs api $A ip/address --stream --via native-api --port $API_PORT --username $U --password $P
+```
+
+The print completes on its own (`stopReason=completed`) with one `re` frame
+per row (`rows` equals a one-shot GET's row count); a leading notice and the
+summary carry `tip/stream-print` naming `ip/address/listen`. It never becomes a listen.
+
+### L18. Zero-row ticks are `!empty` frames and do not use up `--count`
+
+```bash
+centrs api $A ip/firewall/raw/print -X POST -f interval=1 --stream --count 1 --duration 2500ms --via native-api --port $API_PORT --username $U --password $P
+```
+
+On the CHR's empty raw table, each tick is a frame with `reply=empty` and
+`data=null`; at least two arrive. They do not count toward `--count 1`, so the
+stream ends on `duration-elapsed` with `rows=0`.
+
+Loopback regressions in `test/integration/api-stream-command.test.ts` also
+exercise natural/empty completion, `!empty` frames, row-only `--count`,
+`afterStop`, the stream tips, `--format ndjson`, terminal `ret`,
+first/midstream trap, unsolicited interruption, fatal/close, and nonzero
+process exit with the failure summary on stdout. Device-dependent examples
+L6–L18 run in `test/integration/api-listen.test.ts` with validation enabled.
+
 ## fanout (multi-target, F…)
 
 These run against a CDB fixture with two records sharing group `$G`: record 0 is
@@ -432,7 +598,7 @@ the live CHR (comment `board=chr`), record 1 is an unreachable host (comment
 (`data = { summary, targets[] }`; outer `ok` = orchestration success; per-target
 failures are inner `ok:false`), with the granular exit code (0 all-ok / 2 partial /
 1 all-failed or orchestration error). See `test/integration/api-fanout.test.ts`.
-The `--raw`/`--listen` + fan-out guards are network-free and validated in
+The `--raw`/`--stream` + fan-out guards are network-free and validated in
 `test/integration/cli-smoke.test.ts`.
 
 ### F1. `--group` fans a GET out; a dead target is an inner failure
@@ -525,6 +691,28 @@ target fails deterministically: inner `ok:false` with
 `error.code=target/unresolved` (never a `transport/dns` attempt on `"__default__"`).
 `data.summary = { total: 1, ok: 0, failed: 1 }`. Exit code 1 (every target failed).
 
+## `--query` grammar (#397)
+
+`--query` takes the `print where` grammar shared with `retrieve --query`. The
+test seeds `qa-397` address-list rows, one of them disabled with comment `x>y`.
+
+### QA1. A bare boolean is `=yes`, on either transport
+
+```bash
+centrs api $R ip/firewall/address-list --query 'list=qa-397 and disabled' --proplist address --username $U --password $P
+centrs api $A ip/firewall/address-list --via native-api --query 'list=qa-397 and disabled' --proplist address --port $API_PORT --username $U --password $P
+```
+
+Both return only the disabled row's address.
+
+### QA2. A value containing an operator stays one value
+
+```bash
+centrs api $R ip/firewall/address-list --query 'comment=x>y' --proplist address --username $U --password $P
+```
+
+Returns the row whose comment is `x>y`; the query word sent is `comment=x>y`.
+
 ## quickchr targets (#134)
 
 `$NAME` is the machine name of a running quickchr-managed CHR. Host/port/auth

package/commands/devices/README.md

@@ -65,7 +65,15 @@ inert. (Earlier drafts said "the comment is not a lookup key" — superseded.)
 When `<router>` matches an entry (by `target` or a lookup key), credentials and
 other CDB-resident fields load from that entry. If nothing matches, the call
 still proceeds but `--username` / `--password` (or `CENTRS_USERNAME` /
-`CENTRS_PASSWORD`, or a `__default__` record) become mandatory.
+`CENTRS_PASSWORD`, or a `__default__` record) become mandatory. The one
+exception is a **pinned** CDB (`--cdb-file`, `CENTRS_CDB_FILE`,
+`CENTRS_CDB_PASSWORD`, or a `centrs.env` CDB path) with no `__default__`
+record: a DNS name or identity that matches nothing fails closed with
+`cdb/not-found-target`, because it can't be told apart from a mistyped record.
+An address that matches nothing still proceeds as a literal host: an IPv4 or
+IPv6 literal (optionally with a port, IPv6 as `[…]:port`), an `http(s)://` URL,
+or a MAC. On MCP every target must still be registered
+(`cdb/target-not-registered`).
 
 ### Ambiguity
 
@@ -326,8 +334,8 @@ runs produce stable diffs.
 - A multi-target **write** is gated by `--yes`, confirmed once up front (not per
   target); without it the error/tip names the blast radius (how many routers).
   `--force` stays scoped to destructive `devices` CDB mutations.
-- Commands that are not safe to fan out (`terminal`, and `api --stream` /
-  `--listen`) reject a multi-target selection with `usage/fanout-not-supported`.
+- Commands that are not safe to fan out (`terminal`, and `api --stream` or a
+  `/listen` endpoint) reject a multi-target selection with `usage/fanout-not-supported`.
 
 ## Subcommands
 

package/commands/execute/README.md

@@ -6,7 +6,7 @@ CLI-shaped commands — there is no separate `update` command.
 
 Status: `rest-api`, `native-api`, `mac-telnet`, and `ssh` are `CHR-passed` (see
 `docs/MATRIX.md` and `commands/execute/examples.md`, examples 1–11 over REST,
-12–19 over the native API, 20–22 over mac-telnet, and S1–S4 over ssh, green via
+12–19 over the native API, 20–22 over mac-telnet, and S1–S5 over ssh, green via
 `bun run test:integration`), including multi-target fan-out (see **Target
 selection**, examples F1–F5). `romon` and `winbox-terminal` remain
 `not-started`. SNMP is retrieve-only and rejects `execute`.
@@ -136,14 +136,28 @@ selection**, examples F1–F5). `romon` and `winbox-terminal` remain
   mac-telnet. Callers that want IP-level execution may opt into ARP-based
   MAC → IP resolution with `--resolve arp` (plus `--via native-api`/`rest-api`)
   before protocol selection.
+- An explicit `http(s)://host[:port]` target (positional, `--host`, or
+  `CENTRS_HOST`) names the REST service: with no `via` pinned anywhere,
+  auto-selection picks `rest-api` and keeps the URL's scheme and port
+  (`meta.settings.via` source `default` / `via:target-url`). Otherwise
+  auto-selection picks native-api. On the IP transports (native-api, REST,
+  ssh), a port typed into the target (`host:port`, `http://host:port`,
+  including an explicit `:80`/`:443`) is honored. The port settings ladder
+  (`--port`, `CENTRS_PORT`, a CDB `port=` comment, config) wins over it, and
+  the transport default comes last. The port carried by a matched CDB
+  record's `target` is not applied to native-api. mac-telnet addresses the MAC,
+  so its `--host`/`--port` are only the UDP delivery endpoint.
 - When the resolved transport is mac-telnet and **no** username or password is
   resolved from any source, execute emits a `tip/mac-telnet-no-credentials`
   pointer: mac-telnet logs in with RouterOS credentials over **MTWEI** (MD5 is
   refused by current RouterOS), so an empty login is rejected at connect time.
   It is a tip, not an error — the call is still attempted.
 - Default output is human-readable `text`; pass `--json`/`--format json`
-  (or set `CENTRS_FORMAT=json`) for the structured envelope. Errors always
-  render as `[code] summary` + `Fix:` lines in text mode.
+  (or set `CENTRS_FORMAT=json`) for the structured envelope. In text mode every
+  command renders errors the same way (`formatCentrsErrorText`): `[code] summary`,
+  then `At:` (RouterOS position or offline byte span), `Device said:` (RouterOS's
+  own words), `Fix:` and `Details:` when present. `--verbose` adds the full
+  `context`.
 - CDB comment-kv metadata may provide per-target `via`, `port`, and `ssh-key`
   overrides; CLI/API arguments still win.
 - RoMON and WinBox Terminal are lower priority than mac-telnet until their
@@ -189,6 +203,10 @@ with the first SSH consumer, `transfer`/sftp; `execute / ssh` (this command) and
 `terminal / ssh` followed as separate transports over the same host-`ssh`
 plumbing (`src/protocols/ssh.ts`) — all three SSH cells are `CHR-passed`.
 
+A selected key adds `IdentitiesOnly=yes`, preventing fallback to unrelated
+agent keys. Explicit OpenSSH `IdentityFile` configuration still applies; see
+[`terminal` → SSH key selection](../terminal/README.md#ssh-key-selection).
+
 Over SSH — like mac-telnet — `execute` is a **console transport**: it runs a
 CLI line and returns text (`SshExecClient`, one `ssh user@host "<command>"` per
 command; validation reuses the same `:put [:parse …]` gate), so structured
@@ -229,6 +247,16 @@ many tokens):
   the command; no `--` needed). One `--quickchr` stays single-target; repeating
   it fans out; mixing it with positionals or CDB selectors is
   `usage/conflicting-flags` (constitution: resolution providers).
+- `execute --host http://192.0.2.10:8080 '/system/resource/print'` (or
+  `execute --host <host|url> -- <command>`) — the `--host` **flag** stands in
+  for a missing `<target>`: a lone positional is the command, and nothing
+  before `--` is fine. There is no `<target>`, so there is no CDB lookup and no
+  record credential can be picked up; auth comes from flags, env or config.
+  Two or more positionals without `--` keep the legacy split, so
+  `execute <mac> <command> --via mac-telnet --host <udp-host>` (the mac-telnet
+  delivery override) is unchanged. `CENTRS_HOST` never changes positional
+  parsing: `execute '<command>'` with it set still reads the lone positional as
+  the target.
 
 Because `execute` is the primary **write** path, a write-shaped fan-out is gated
 by **`--yes`**, confirmed **once** up front; without it