Search run lifecycle
Preview to confirmation to stream to collection — previewToken binding, run status and retry, and cancelling an in-flight pipeline.
search run is the only command with a multi-stage lifecycle. Getting the order
wrong is how runs get paid for twice.
The stages
preview → confirm → stream → collection
1. Preview
eximagent --dry-run search run --product "roasted coffee" --location DE --hsCode 090111
Returns the plan, the expected cost, and a previewToken.
2. Confirm with the same token
eximagent search run \
--product "roasted coffee" --location DE --hsCode 090111 \
--confirmed --previewToken <token>
3. Block on the stream
The kickoff response returns a runId. Results land only at completion.
eximagent stream --run-id <runId>
Block until the terminal {kind: "complete"} event. Rows read before it are a
partial set that gives no indication of being partial.
4. Read the collection
eximagent run summary --run-id <runId>
eximagent collection get --name <name>
Managing a run
eximagent run status --run-id <runId>
eximagent run summary --run-id <runId>
eximagent run retry --run-id <runId>
eximagent run cancel --run-id <runId>
eximagent pipeline stop --run-id <runId>
run retry is idempotent — it resumes rather than re-charging for completed
work. pipeline stop halts an in-flight discovery pipeline.
Refine instead of re-running
If the shape of the results is wrong, refine the existing run:
eximagent search refine --run-id <runId> --product "specialty green coffee"