@tikoci/centrs 0.1.6 → 0.1.8-next.0

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).
 
@@ -112,15 +129,18 @@ gate is `/console/inspect` — **not** `:put [:parse]`:
   does) answers normally on the same build. See the 7.12.2 finding in
   `AGENTS.md` (GH#343).
 - **Carve-out:** a script-shaped `POST /rest/execute` is a CLI string, not a path,
-  so the inspect gate is `not-applicable` (`meta.validation.semantic`); RouterOS
-  re-validates on the run. Until GH#354 that carve-out meant the script was sent
-  with *no* preflight at all. It is now gated by the offline stage (constitution:
-  validation) — the same analyzer `explain` publishes, run over the `script`
-  field with no connection, so a syntax fault is a byte span in
-  `error.context.span` instead of a round trip. `meta.validation.stages[]` shows
-  the offline stage `passed` and the device stage `skipped` with its reason. A
-  missing or blank `script` is still `input/invalid-command`, not a syntax
-  rejection.
+  so structured inspect is `not-applicable` (`meta.validation.semantic`). It
+  follows the CLI-string pipeline instead: offline analysis, then live
+  `:put [:parse ...]`, then run. An offline rejection is still a byte span with
+  no connection; an offline pass or abstention continues to the device stage.
+  `meta.validation.stages[]` reports both decisions. A missing or blank `script`
+  is still `input/invalid-command`, not a syntax rejection. Validation passing
+  is not the run succeeding: `as-string` makes the console's own text the reply
+  body, so a runtime rejection arrives as an HTTP-200 `ret`. `/execute` output
+  is normalized through the same grounded result table `execute` uses, so
+  `no such item` fails the envelope with a `routeros/*` code while the stages
+  stay `passed`. Ordinary output that merely contains a fault string is
+  unaffected — the result matchers are anchored, not substring.
 - Structured path requests are **not** offline-gated. The input is a path plus a
   body, not a CLI string, and an offline *path* gate collides with GH#211's
   unlisted-path decision. On the success path `meta.validation.stages[]` is
@@ -168,27 +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. `--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)).
@@ -156,7 +157,8 @@ centrs api $R execute -X POST -f script=':put [/system/identity/get name]' --use
 
 Envelope: `ok: true`, `data` is string-shaped and contains the CHR identity;
 `meta.validation.semantic=not-applicable` (script, not a path) and
-`meta.validation.stages` is `offline: passed` then `device: skipped`.
+`meta.validation.stages` is `offline: passed` then live `device: passed` from
+`:put [:parse ...]`.
 
 ### 16b. The `/execute` script is gated offline (GH#354)
 
@@ -173,10 +175,46 @@ Envelope: `ok: false`, `error.code=validation/syntax`,
 `error.context.span={"start":5,"end":6}`, and **not** a `transport/*` code.
 `meta.validation.stages` is `offline: failed` then `device: skipped`.
 
-### 17. `--via rest-api --listen` is rejected
+### 16c. Offline pass continues to live `:parse`
 
 ```bash
-centrs api $R ip/address --listen --via rest-api --username $U --password $P
+centrs api $R execute -X POST -f script='/ip/address/add no-such-arg=x' --username $U --password $P --yes
+```
+
+Envelope: `ok: false` with a device validation code
+(`validation/unknown-attribute`, or `validation/syntax` on older RouterOS), and
+`meta.validation.stages` is `offline: passed` then `device: failed`. Offline
+acceptance remains `runtimeAcceptance: not-proven`; it never suppresses the live
+stage.
+
+### 16d. A runtime rejection in `/execute` output is not `ok: true`
+
+```bash
+centrs api $R execute -X POST -f script='/ip/service/set www-ssl certificate=nope' --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=routeros/invalid-value`. `as-string` makes
+the console's own text the reply body, so RouterOS carries this rejection in an
+HTTP-200 `ret`; the validation gate stays `passed` because it did pass — the
+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`.
+
+### 16e. Wrong credentials: the device stage is not reached (GH#435)
+
+```bash
+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
@@ -207,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.)
@@ -239,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
@@ -308,30 +355,54 @@ stdout is the bare rest-style array (string values); exit code 0.
 centrs api $A execute -X POST -f script=':put [/system/identity/get name]' --via native-api --port $API_PORT --username $U --password $P --yes
 ```
 
-Envelope: `ok: true`, `data` contains the CHR identity.
+Envelope: `ok: true`, `data` contains the CHR identity and validation reports
+offline plus live `:parse` stages passed.
+
+### N8b. Native `/execute` also rejects at live `:parse`
+
+```bash
+centrs api $A execute -X POST -f script='/ip/address/add no-such-arg=x' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`; the accepted version-specific validation code is
+`validation/unknown-attribute` or `validation/syntax`, with stages
+`offline: passed`, `device: failed`.
+
+### N8c. Native `/execute` runtime rejection fails the envelope
+
+```bash
+centrs api $A execute -X POST -f script='/ip/service/set www-ssl certificate=nope' --via native-api --port $API_PORT --username $U --password $P --yes
+```
+
+Envelope: `ok: false`, `error.code=routeros/invalid-value`, with the validation
+stages still `passed` — the same normalization as REST, since both adapters
+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
@@ -350,11 +421,174 @@ 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
+
+```bash
+centrs api $A ip/address --stream --duration 200ms --timeout 1s --via native-api --port $API_PORT --username $U --password $P
+```
+
+A stream stopped by `--duration` or Ctrl-C sends `/cancel` and waits up to
+`--timeout` for the router's acknowledgement (the interrupted `!trap` and
+`!done`). If none arrives, centrs closes the session itself. The summary still
+reports its stop reason (`duration-elapsed` or `interrupted`), exit code is 0,
+and `warnings` carries `transport/cancel-unacknowledged`. A router that answers
+inside the window gets no warning. `--count` sends `/cancel` without waiting,
+so it exits at once and never warns (#385).
+
+RouterOS on CHR always acknowledges `/cancel`, so this example runs against a
+loopback native-API peer that ignores it, as a real CLI process:
+`test/integration/api-stream-cancel.test.ts` covers `--duration`, SIGINT,
+`--count` and the cooperative control. The session-level cases (silent peer,
+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…)
 
@@ -364,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
@@ -457,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