Skip to content

REQ-O-003: --limit and --cursor Pagination Flags

Tier: Opt-In | Priority: P0

Source: §5 Pagination & Large Output

Addresses: Severity: High / Token Spend: High / Time: High / Context: Critical

Description

The framework MUST register --limit <n> and --cursor <token> as standard flags on all list commands. --limit controls maximum items returned. --cursor accepts an opaque pagination token from the previous response's pagination.next_cursor. The cursor MUST be stateless (self-contained, not dependent on server-side session). The framework MUST reject --cursor values that are expired or invalid with a structured error.

Acceptance Criteria

  • --limit 50 returns at most 50 items
  • Passing pagination.next_cursor from response N as --cursor returns the next page
  • An invalid --cursor value returns a structured error, not a crash
  • Cursor tokens are URL-safe strings (base64url or similar encoding)

Schema

Type: response-envelope.md

Pagination metadata appears in meta: meta.cursor holds the next-page token, meta.total holds the total item count when known, and meta.page_size reflects the effective limit used.

Wire Format

First page:

$ tool list-deployments --limit 2 --output json

{
  "ok": true,
  "data": [
    { "id": "d1", "status": "complete" },
    { "id": "d2", "status": "running" }
  ],
  "error": null,
  "warnings": [],
  "meta": { "duration_ms": 55, "cursor": "eyJwYWdlIjoyfQ", "page_size": 2, "total": 47 }
}

Next page:

$ tool list-deployments --limit 2 --cursor eyJwYWdlIjoyfQ --output json

{
  "ok": true,
  "data": [
    { "id": "d3", "status": "failed" },
    { "id": "d4", "status": "complete" }
  ],
  "error": null,
  "warnings": [],
  "meta": { "duration_ms": 48, "cursor": "eyJwYWdlIjozfQ", "page_size": 2, "total": 47 }
}

Example

The framework registers --limit and --cursor on list commands at opt-in time.

app = Framework("tool")
app.enable_pagination_flags(default_limit=20, max_limit=100)

# tool list-deployments --limit 10  →  first 10 items + meta.cursor
# tool list-deployments --limit 10 --cursor <token>  →  next 10 items
Requirement Tier Relationship
REQ-F-018 F Provides: pagination metadata shape used in meta
REQ-F-019 F Provides: default limit applied when --limit is absent
REQ-O-004 O Composes: --stream emits pagination metadata as the final JSONL line
REQ-F-004 F Provides: ResponseEnvelope carrying meta.cursor