Commands that list items, such as list, search, and categories subcategories ID, read every page of the collection and print the items together. You never write paging code: narrow the list with flags instead.

​
Limit results

--limit prints at most that many items. Paged reads stop requesting pages as soon as they safely can. --limit 0, the default, prints every item.
When a limited list spans several pages, end --sort with a unique field, such as code:desc,id. Items that share a sort value may come back in a different order on each page.

​
Filter with a query

--query filters with the Emporix q parameter, passed as given. Conditions separated by spaces must all match; quote the filter so your shell keeps it in one piece. Emporix rejects a malformed filter, but not an unknown field name, which may match nothing or everything. When a command already filters with a query of its own, your --query is added to it, so it can only narrow the result.

​
Search commands

search commands, such as products search, send the query in the body of a POST request that changes nothing, and print their results as the matching list does. Pass --body FILE to send a whole JSON body instead of --query, or --body - to read it from standard input.

​
Sort results

--sort orders a list with the Emporix sort parameter, passed as given: fields separated by commas, each optionally followed by :asc or :desc.

​
Which lists take which flags

Each list supports what its Emporix service supports. epx <command> --help shows the flags of a command. Field names for --query and --sort are mostly those of -o json, but not always. Products, for example, sort by creation date as metadataCreatedAt. Check the Emporix API reference of the service.

​
How paging works

A list reads 100 items per page, up to 1,000 pages (10,000 with --stream). It fails with exit code 1 when paging is visibly inconsistent: an item read twice, or a count that differs from the total Emporix reports. Without --stream, it prints nothing unless every check passes. Like any paged read, a list can’t notice an item that changes while its pages are read. Some services need a different read, and the command’s help says so:
  • Collections that Emporix returns whole, such as category trees and configurations, are read with one request.
  • Some lists can’t check their total, because Emporix sends none or fails when asked for it. An item that moves between pages while they’re read can then show twice or be missed.
  • Emporix orders countries and IAM users differently on every request, so epx reads each as one page. IAM users fit in one page of up to 500; on a tenant with more, iam users list fails.
  • The change history (changelog list) covers the last 30 days unless you filter on occurredAt. On an active tenant, read a closed range in the past, or use --limit.