Search for Orders and Use the Work Queue

Finding the right orders is where most shipping sessions start. The CLI supports natural language search, structured filters, and a product-defined work queue for "what should I ship?" This article shows how to search confidently without silent empty results.

In this article, we will search with natural language and structured JSON, use the work queue for shippable work, read empty-result context the right way, and connect search to shipments.

Real-World Example

We are opening the day and want ready-to-ship orders from the last two months, not four-year-old sample imports and not every order stuck in a custom hold status.

Before We Begin

This article assumes that:

• You are authenticated
• You understand that status names are defined by your account
• Optional: postsale run available if you want the work queue via natural language (the postsale orders work-queue subcommand needs no LLM key)

Search with natural language

Here's how:

postsale orders search --query "shipped last week to California"
postsale orders search --query "orders from last 7 days" --page-size 50
postsale orders search --query "..." --all

Useful flags:

• --page / --page-size (max 150, default 50)
• --all streams NDJSON for every matching page
• --max-items caps --all (default 10000)
• --compact projects each order to id, number, status, date, total, ship_to, and an item count — about 6.4x smaller (a 50-order page drops from ~55KB to ~8.5KB). Works with --all. Response-level fields, including _cli_meta.empty_result_context, are preserved.
• --human pretty-prints for reading

Reach for --compact when triaging and full records when acting: creating a shipment or quoting rates needs weights, SKUs, and the full destination address, which the projection drops. postsale orders get <order_id> fetches the full record for anything you picked out of a compact list.

The natural language path may include interpreted_query so you can see how the backend understood you.

Search with a structured filter

When you already know the filter shape:

postsale orders search --json '{"conditions":{...}}'
postsale orders search --input filter.json
postsale schema orders.search

Use structured search when natural language is ambiguous or when you are encoding a known report.

Prefer the work queue for "what should I ship?"

Guessing status strings is the most common source of silent zeros (successful calls that return no orders).

Ask for the work queue directly — no LLM key required:

postsale orders work-queue
postsale orders work-queue --human          # readable rendering
postsale orders work-queue --all-time       # ignore the recency window
postsale orders work-queue --statuses "Ready to Ship,On Hold"

Or through the agent, which reaches the same definition:

postsale run "what should I ship? explain the applied filters and exclusions"

How the work queue is defined

Status matching is normalized, so account spellings of 'ready to ship', 'awaiting shipment', and 'unfulfilled' count. Pass explicit statuses only after confirming them with a human.

When search returns nothing

A zero-order result may include _cli_meta.empty_result_context — both from the agent tool search_orders AND from the direct postsale orders search command (so a coding agent driving the CLI gets the same honesty signal without an LLM key):

• How the filter was applied
• Alternate counts (for example total orders with no filter, or the same filter without status)
• Account status vocabulary

If alternates are nonzero, the filter missed. The account is not necessarily empty.

From orders to shipments

Order search does not embed full shipment records. Continue with:

postsale shipments list --query "..."
postsale shipments get --reference <order_id>

See Orders, shipments, and labels.

Direct CLI without the agent

1. List statuses via postsale run "list order statuses for this account" or your account UI.
2. Search with natural language or structured JSON using your status names.
3. If the result is empty, widen filters and read interpreted_query on natural search.
4. Reads are free; experiment with searches as much as you like.

The full structured filter that mirrors the work queue lives in AGENTS.md for agent authors. Do not invent field names.

Good to Know

List statuses via the agent:

postsale run "list order statuses for this account"

Additional Reading

• Ship one order
• Shipping, labels, and rates
• orders command stub
• Agent honesty notes: honesty-contracts