Preview Work with Dry-Run
Preview what the agent would do without charging anything, and read which writes were simulated and which still ran.
postsale run --dry-run lets you rehearse high-risk agent tools without charging carriers or running destructive deletes. It is one of the best habits you can build before live label purchase.
In this article, we will explain what dry-run simulates, call out what still writes for real, read the audit fields on the envelope, and connect dry-run to parallel batches.
Real-World Example
We want to see whether the agent would call
purchase_labelsfor a shipment id, and with which arguments, before we pass--yes.
Before We Begin
This article assumes that:
postsale runworks for a simple read intent- You have a shipment or order id to mention in the intent (optional but helpful)
What dry-run does and does not do
Dry-run is a targeted intercept list, not a global "nothing writes anywhere" switch.
What is simulated
- Money-moving:
create_shipment,purchase_labels,void_shipment - Destructive deletes and
create_end_of_day_manifest - Status writes:
set_order_status,bulk_set_order_status
Simulated calls return a payload that includes "dry_run": true, the tool name, a note that it was not executed, and input_received.
Because those tools do not actually run, they do not require confirmation under dry-run.
One read still happens for purchase_labels when POSTSALE_TEST_LABEL_MODE is set: the CLI fetches every shipment first (the same call get_shipment makes) so the preview shows the test_label_required refusal a real run would produce. The simulated envelope then carries test_label_verified and says so in its note. See the safety model.
Still executed for real
create_orderupdate_orderupdate_shipment- Tagging
- Bulk field edits on shipments
- Filter create and update
Warning
If the model creates an order under dry-run, that order can land in the API. Prefer read-only intents when you need zero writes.
Here's how to rehearse a money path
- Run a dry-run intent:
postsale run --dry-run "Purchase a PDF label for shipment <shipment_id>"-
Inspect the envelope fields that matter for dry-run:
simulated_effects,confirmed_effects,tool_calls, andsummary. -
Try related rehearsals:
postsale run --dry-run "void shipment <shipment_id>"
postsale run --dry-run "Ship order <order_id> with the cheapest carrier"Success looks like money tools appearing under simulated_effects without carrier charges, and a summary that matches what was blocked or allowed.
Parallel batches and dry-run
money-moving parallel batches still require batch authorization under dry-run. Subagents might still perform non-intercepted writes. The batch gate stays fail-closed. See [Parallel batches](./parallel batch.md).
Good to Know
| Field | Meaning |
|---|---|
simulated_effects | Intercepted tools as received (before live validation or dedup) |
confirmed_effects | Real durable writes that actually happened |
Outside dry-run, simulated_effects is present and empty.
| Symptom | Likely cause | What to do |
|---|---|---|
| Order created during dry-run | create_order not intercepted | Use read-only intents |
| Empty simulated_effects | Model never called money tools | Check tool_calls; rephrase |
| Parallel batches still asks to authorize | Expected | Approve, AUTOAUTH, or reword |
Additional Reading
On this page
Related