CLI Workflows

Repeatable operational workflows — and the deterministic form to use once they run unattended.

CLI Workflows

Common operational flows, in two forms: natural language for working interactively, and stateset-direct for the same workflow once it runs unattended.

Every write needs --apply. Run the read steps first — they cost nothing and they tell you whether the write is the one you meant.

Order fulfilment

Interactively:

stateset "show me pending orders"
stateset "show order #12345"
stateset --apply "ship order #12345 with tracking FEDEX123"

Scripted — same effect, no interpretation layer:

stateset-direct orders list
stateset-direct --apply orders ship <order-id> FEDEX123

Returns processing

stateset "list returns awaiting review"
stateset --apply "approve return RMA-1001"
stateset --apply "refund return RMA-1001 for $29.99"

Approving a return doesn’t restock anything — markReceived does, when the parcel actually arrives. Refunding before receipt means you’ve paid out on an item that may never come back. See the returns workflow.

Inventory adjustment

stateset --apply "adjust inventory for sku WIDGET-001 by -5 at warehouse LA"

stateset-direct --apply inventory adjust WIDGET-001 -5 "Sold 5 units"

Always pass a reason. Adjustments are recorded as movements with an audit trail, and a reason is what makes a later discrepancy traceable to the correction that caused it.

Batch work

For repeated operations, put the requests in a file rather than looping the shell:

stateset --apply --batch requests.txt

Sessions carry context, so a multi-step flow can refer back:

stateset --apply "create an order for that customer with 2 widgets at $29.99"
stateset --apply --resume <session-id> "ship that order with tracking ABC123"

Parsing output

stateset --json "show me pending orders" | jq '.orders[].id'

Use --json whenever something downstream reads the result. Prose output shape isn’t a contract; the JSON shape is.

Promoting a workflow to production

Once a workflow is doing real work on a schedule, move it off natural language:

Stage	Form
Exploring	stateset "…" — read-only, no flag
Confirming	stateset --apply "…" — watch what it does
Scripted	stateset-direct --apply … — deterministic
Scheduled	stateset-autonomous — jobs, policies, approvals

Don’t leave natural language in a cron job. The same sentence can resolve to a different action as the model changes, and a scheduled task is exactly where nobody is watching when it does.

Related

• CLI Reference — all three binaries
• CLI Safety Model
• Order Lifecycle
• Scenarios