Skip to main content
Two flag pairs bound almost every read in the CLI: --limit / --all decide how many records you get, and --since / --until decide which time range they come from. Both pairs behave identically on every command that accepts them — this page states the rules once; the per-command flag tables live on the command pages.

​
--limit vs --all

Every list command accepts both flags, with one meaning each:
  • --limit N — the first N items;
  • --all — the complete result, however many pages that takes;
  • neither — one server page of 20 items on a cursor-paginated list (octolens mentions list and friends);
  • both — a contradiction, refused before any request is made: exit 2 with CONFLICTING_FLAGS.
The small per-workspace collections — keywords, feeds, tags, members, notifications — are bounded: the API returns them whole, so there is no cursor to walk. The same two flags still work there and mean the same thing to you; the CLI applies them as a client-side head of the already-complete result, and omitting both returns the full collection rather than one page:

​
pagination.nextCursor in --json

Every list’s --json document carries a pagination.nextCursor field: an opaque string while more records exist beyond what was returned, and null when the listing is complete. Three consequences:
  • after --all, nextCursor is always null — the collection was drained;
  • on a bounded list it is always null — the collection arrived whole, and --limit was only a client-side head of it;
  • a non-null cursor is the signal to re-run with a larger --limit (or --all) if you wanted everything — the CLI walks cursors internally, so the value itself matters only to direct callers of the v2 REST API, where the cursor parameter lives.
The per-list document shapes, nextCursor included, are in the Returns sections of the command pages.

​
--since / --until shapes

Both flags take ISO 8601, in two shapes:
  • a date — 2026-06-01;
  • a datetime — 2026-06-01T09:30:00Z.
A bare date expands to the whole day it names: as --since it means the start of that day, as --until the end of it, so --since 2026-06-01 --until 2026-06-01 is the full one-day window — the named day is never silently excluded. A datetime is exact and never adjusted. Anything else is refused client-side, before any request: a non-ISO shape or an impossible calendar date (2026-02-30) exits 2 with INVALID_DATE naming the flag and value, and a window whose end precedes its start exits 2 with INVALID_WINDOW — an inverted window cannot match anything, so the CLI refuses to ask the API and then report the inevitable empty result as if the data did not exist.

​
No default window

Mention reads apply no default time window: omit both flags and the range is unbounded — the web app’s feed opens on a recent slice, but the CLI does not copy that default, so octolens mentions export with no window is your entire history. Each bound also works alone: only --since leaves the end open, and only --until reaches back to your oldest mention. The analytics group is the one exception, because an aggregation needs a window to aggregate over: there --since and --until must be passed together (only one of the pair exits 2 with INCOMPLETE_WINDOW), and omitting both applies the server’s default window — the flag table on Analytics & insights states it.