@agentcentral/cli 0.1.4 → 0.1.6

package/README.md

@@ -76,6 +76,29 @@ agentcentral tools call update_keyword_bids @bids.json \
   --yes --idempotency-key "$(uuidgen)"
 ```
 
+#### Auto-pagination (`--all` / `--paginate`)
+
+Some live-API read tools return their results across multiple pages. Pass `--all` (alias `--paginate`)
+to `tools call` and the CLI follows the server's continuation block, fetching every page and emitting
+the concatenated rows:
+
+```bash
+agentcentral tools call get_sponsored_ads_entities_live '{"ad_product":"SP"}' --all
+agentcentral tools call get_audience_segments '{}' --all --format ndjson
+agentcentral tools call get_report_document '{"report_document_id":"amzn1.tortuga..."}' --all --format csv --output report.csv
+```
+
+Notes:
+
+- `--all` is reads only. Combining it with a write tool or with `--yes` is a usage error (exit 2).
+- For `json`, `csv`, `table`, and `markdown`, the rows from every page are accumulated and rendered
+  once. For `ndjson`, each page's rows stream to stdout as they arrive (incremental); with `--output`,
+  ndjson buffers and writes the file once instead.
+- Auto-pagination stops at a 100-page cap and warns on stderr if the cap is hit, so narrow the query
+  to fetch the rest.
+- A tool whose response carries no pagination block is a single call plus a one-line stderr note, not
+  an error. This is also how `--all` degrades gracefully against an older server.
+
 ### Convenience read commands
 
 Thin wrappers over the same hosted read tools. Each maps friendly flags onto the exact parameters its
@@ -122,9 +145,13 @@ Every command accepts: `--format/-f json|ndjson|table|csv|markdown`, `--output/-
 `--profile/-p <name>`, `--timeout <ms>`, `--limit <n>`, `--quiet/-q`, `--no-color`, `--verbose`,
 `--request-id <id>`, `--yes/-y`, `--idempotency-key <key>`, `--api-key-stdin`.
 
-When `--limit <n>` is set and the result comes back with exactly `n` rows, the CLI emits a best-effort
-truncation WARNING to stderr. The hosted server exposes no truncation flag or total-row count, so this
-is a heuristic, it only fires when `--limit` is set, and it never touches stdout.
+`tools call` also accepts `--all` / `--paginate` (auto-pagination, reads only; see above).
+
+Truncation is reported authoritatively from the server, not guessed. When the result envelope says it
+hit the row limit (`more_rows_possible` / `limit_reached`), the CLI warns on stderr with the row count
+(and the exact `returned N of M matching rows` phrasing when the tool supplies a total). When more
+pages are available, it instead notes that you can pass `--all` to fetch them. These messages go to
+stderr only (honoring `--quiet`) and never touch stdout.
 
 ## Exit codes