CLI Safety Model

Read-only by default, explicit write intent, and how to scope an agent that holds the CLI.

CLI Safety Model

The CLI is read-only until you say otherwise. Every write — creating an order, adjusting inventory, moving money — requires an explicit --apply.

That default exists because the CLI is frequently held by an agent, and an agent exploring your data should not be able to change it as a side effect of looking.

Read-only by default

stateset "show me pending orders"                    # safe
stateset-direct inventory stock WIDGET-001           # safe

No --apply, no mutation. A misinterpreted request costs you a wrong answer, not a wrong write.

Explicit write intent

stateset --apply "ship order #12345 with tracking FEDEX123"
stateset-direct --apply inventory adjust WIDGET-001 -5 "Sold 5 units"
stateset pay --apply --to <address> --amount 50 --chain solana

The flag is deliberately not inferrable from the sentence. “Ship order 12345” without --apply describes what would happen; it doesn’t do it.

Why this shape

Property	Effect
Fail-safe default	Forgetting a flag under-permits rather than over-permits
Auditable intent	A write is a distinct decision visible in shell history and logs
Safe exploration	You can probe production data without a plan to change it

This is the same principle as the decision gate: the default outcome of ambiguity is no action, not a guess. Forgetting --apply gets you a read; there is no way to forget your way into a write.

Scoping an agent

--apply is the coarse control. For an agent, layer these:

Separate the read path from the write path. Give an exploratory agent a wrapper that cannot pass --apply at all, rather than trusting it to omit the flag.

Use stateset-direct for anything automated. The natural-language binary interprets phrasing, so the same instruction can resolve differently as the model changes. Deterministic commands produce the same action every run.

Point at a copy first. --db <path> selects the database. Run a new agent against a copy of the store before pointing it at the real one.

cp store.db store-test.db
stateset --db ./store-test.db --apply "…"

Use --json when parsing. Prose output shape isn’t a contract; the JSON shape is.

The engine’s own guardrails still apply underneath the CLI — idempotency keys on order and payment writes, terminal-state guards on cancellation, High-Value Action thresholds. --apply grants permission to attempt a write; it does not bypass those. See API hardening.

What --apply does not protect against

It is a gate on intent, not on correctness. --apply "refund order #12345 for $2999.00" will attempt exactly that. For value-based limits and human approval on consequential actions, use the review gate and High-Value Action threshold.

Related

• CLI Reference
• CLI Workflows
• API Hardening