Filters and paging
How to narrow a list with --filter, how to sort it, and how --limit, --all and --cursor walk through a long list.
Most list commands (pitch list, article list, datasource list and so on) can narrow what they return
with filters and walk through long results a page at a time.
Filters
A filter is written field.operator=value and given with --filter. You can repeat the flag.
nuvelics pitch list --filter status.eq=newFilters on different fields are combined: a result must match all of them.
nuvelics pitch list --filter status.eq=new --filter minSourceCount.gte=3The operator is always required. status=new on its own is refused; there is no default operator.
Discover the fields
Each field accepts only certain operators, and the fields differ from one list to the next. Do not guess:
ask a list what it can be filtered on. A list in JSON form carries a filters.available catalog:
nuvelics pitch list --limit 1 -o json | jq '.data.filters.available'[...,
{"field":"status","kind":"eqIn","facetable":true},
{"field":"newsdeskId","kind":"eqIn","facetable":true},
...](Abridged: a real catalog lists more fields, and these are not the first entries.)
The kind of a field decides its operators:
kind | Operators | Notes |
|---|---|---|
string | eq, in, contains | One of the three per field. contains splits its value on spaces and needs every word to appear, in any order, ignoring case and accents. |
inOnly | in | |
eqString | eq | |
boolean | eq | true or false. |
dateRange | gte, lte | Use either, or both together for a window. Values are ISO 8601 dates, such as 2026-01-01T00:00:00Z. |
nullable | isNull | true or false. |
eqOrNull | eq or isNull | Not both in one command. |
eqIn | eq or in | Not both in one command. |
numericGte | gte | A number. |
Several values with in
Repeat the flag, once per value. There is no comma syntax.
nuvelics pitch list --filter status.in=new --filter status.in=approvedMore examples
nuvelics datasource list --filter enabled.eq=true
nuvelics article list --filter "title.contains=budget vote"
nuvelics pitch list --filter createdAt.gte=2026-01-01T00:00:00Z --filter createdAt.lte=2026-06-30T23:59:59ZQuote a value that contains spaces.
When a filter is refused
A malformed filter is caught by the tool before anything is sent, and fails with the kind usage and exit
code 2. The message names the problem, for example an unknown field, an operator the field does not
accept, or two operators on one field:
invalid filter: field "status" accepts only one operator at a timeFix the filter and run it again. Running it unchanged will not help. In the JSON result,
.data.filters.applied echoes what was applied, so you can confirm your filter took effect.
Stories from the newsroom system
Stories that came from your newsroom system are rows of the same list as the rest. There is no separate
command for them. Use the --source option of story list: nuvelics story list --source nrcs, or
--source pitch for stories a pitch produced.
Sorting
Some lists take --sort. Write -field for descending and field for ascending, and always join the value
to the flag with an equals sign:
nuvelics article list --sort=-publishedAtWithout the =, --sort -publishedAt fails, because the tool reads -publishedAt as another flag. Each
list accepts only its own fields; nuvelics <noun> list --help and the
command reference show them. A list's own default order applies when you give no
--sort.
Paging
These lists are paged: api-key, article, cluster, datasource, invitation, member, pitch,
run, story and usage-events. They share three flags:
--limit <n>stops afternitems in total. The default is 100.--allwalks every page until the list ends. It cannot be combined with--limit.--cursor <cursor>continues from where an earlier command stopped.
Other lists, such as newsdesk list and credential list, return everything in one go and take none of
these.
Continue where you stopped
In JSON output, .data.pagination.nextCursor is set only when --limit stopped the list while there was
more. Pass it back as --cursor:
nuvelics pitch list --limit 50 -o json | jq -r '.data.pagination.nextCursor'
nuvelics pitch list --limit 50 --cursor <the cursor from above> -o jsonWhen the list is finished, nextCursor is null. With --all it is always null, because nothing is left.
In text mode the cursor is printed on standard error as nextCursor: ....
Keep the same filters and sort when you continue. A cursor made under one sort is refused under another.
When you do not know how big a collection is, prefer an explicit --limit and page with the cursor over
--all.