Preview Agent Writes with Dry Run and JSON Output in an Okibi CLI
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.
Preview Agent Writes with Dry Run and JSON Output in an Okibi CLI
Agents that call a write command by mistake can change real data. A generated Okibi CLI prints its results as JSON when you pass --agent or --json (a few commands print text, and sync prints JSON event lines), and it previews any write with --dry-run, so an agent can show what it would send before it sends it. This guide checks both against the acme-orders CLI.
What you will build
A check that a create command previews its request, sends no request at all, and leaves the order count unchanged.
orders create --dry-run -> request preview on stderr + JSON status on stdout -> no request reaches a recording listener, order count unchanged
AI Prompt
Using the generated acme-orders CLI, show that an agent can preview a write without changing data. Requirements: - Run `orders create` with `--dry-run --agent` and a valid customer and item list. - Confirm the output contains `(dry run - no request sent)` and `"dry_run": true`. - Count the orders before and after with `--data-source live --no-cache`. The count must not change. - Point the CLI at a listener that records every request, run a read as a control, run the dry runs, and show that the listener saw only the control request. - Report the API key as masked in the preview. - Run the verification step below before finishing.
Prerequisites
-
The Acme Orders example files,
openapi.json(a fictional orders API spec) andserver.py(a mock server for it). Download them into your working directory:curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/openapi.json curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/server.py
-
acme-ordersgenerated from the Acme Orders example spec and built with Go (okibi generate --spec ./openapi.json --name acme-orders --agent;okibi generate --agentdoes not download the CLI, so wait untilokibi status <run-id> --json(<run-id>isbuild.runIdfrom its output) shows"status": "succeeded", then runokibi pull <run-id>andgo build -o ./acme-orders ./cmd/acme-ordersinside the project), with the binary at./acme-orders. -
The Acme Orders example API (
ACME_API_KEY=demo-key python3 server.py --port 8099) running onhttp://127.0.0.1:8099, andexport ACME_ORDERS_API_KEY=demo-key. -
Okibi CLI
0.2.11.
1. Count the orders
./acme-orders orders list --all --data-source live --no-cache --agent 2>/dev/null | python3 -c "import json,sys;print(len(json.load(sys.stdin)['results']))"
Note the number. The example API starts with 7 orders. --data-source live --no-cache makes the CLI ask the API, so a cached or synced answer cannot stand in for the real count. 2>/dev/null hides the paging events the command prints to stderr.
2. Preview the create
./acme-orders orders create \
--customer-id cus_1 \
--items '[{"product_id":"prd_1","quantity":2}]' \
--dry-run --agent
POST http://127.0.0.1:8099/v1/orders
Body:
{ "customer_id": "cus_1", "items": [{ "product_id": "prd_1", "quantity": 2 }] }
X-API-Key: ****-key
(dry run - no request sent)
{ "action": "post", "data": { "dry_run": true }, "dry_run": true, "path": "/orders", "resource": "orders", "status": 0, "success": false }
The preview goes to stderr and the JSON status goes to stdout, so a script can read the status without the preview. The real output is pretty-printed over several lines, and the samples here are condensed to fit. "success": false with "status": 0 means nothing was sent. The key is masked.
3. Pass the body from stdin
Nested fields do not need shell quoting if the body comes from stdin:
echo '{"customer_id":"cus_1","items":[{"product_id":"prd_1","quantity":1},{"product_id":"prd_2","quantity":3}]}' \
| ./acme-orders orders create --stdin --dry-run --agent
The preview shows both items in the body, and the output ends with the same "dry_run": true status.
4. Prove that no request leaves the machine
An unchanged count shows nothing was created. To show that nothing was even sent, point the CLI at a listener that records every request it receives. Save this as request_log.py:
import http.server, sys
port, log = int(sys.argv[1]), sys.argv[2]
class H(http.server.BaseHTTPRequestHandler):
def handle_any(self):
open(log, "a").write(f"{self.command} {self.path}\n")
self.send_response(200); self.send_header("content-type", "application/json"); self.end_headers()
self.wfile.write(b'{"data": [], "next_cursor": null}')
do_GET = do_POST = do_PATCH = do_PUT = do_DELETE = handle_any
def log_message(self, *a): pass
http.server.HTTPServer(("127.0.0.1", port), H).serve_forever()
python3 request_log.py 9930 requests.log &
LISTENER=$!
export ACME_ORDERS_BASE_URL_OVERRIDE=http://127.0.0.1:9930/v1
# control: a live read must reach the listener
./acme-orders orders list --data-source live --no-cache --agent >/dev/null 2>&1
cat requests.log
# the two dry runs from steps 2 and 3
./acme-orders orders create --customer-id cus_1 --items '[{"product_id":"prd_1","quantity":2}]' --dry-run --agent >/dev/null 2>&1
echo '{"customer_id":"cus_1","items":[{"product_id":"prd_1","quantity":1}]}' | ./acme-orders orders create --stdin --dry-run --agent >/dev/null 2>&1
wc -l < requests.log
kill $LISTENER; unset ACME_ORDERS_BASE_URL_OVERRIDE
GET /v1/orders?limit=3
1
The control read shows up in the log. After both dry runs the log still holds one line, so neither dry run sent a request. (ACME_ORDERS_BASE_URL_OVERRIDE is the CLI's run-time address override. This listener replies with an empty list, which is enough for the control read.)
Verify the result
Run step 1 again. Expected: the same number as before (7 for the example data), and the request log from step 4 holding only the control GET. Neither dry run created an order, and neither sent a request.
How it works
Every generated write command builds the request, prints it with the key masked, and stops before the network call when --dry-run is set. The request log in step 4 is the evidence that no call is made. --agent turns on --json --compact --no-input --no-color --yes, so no prompt can block an agent.
Common issues
Dry run does not validate against the API
The preview confirms what the CLI would send, not that the API would accept it. A request with a customer that does not exist still previews cleanly. The same request sent for real returns HTTP 422 and exit code 5.
"success": false looks like a failure
For a dry run it is expected, together with "status": 0. Check "dry_run": true.
The flags and body fields differ per command
Use acme-orders orders create --help for the flags. --stdin accepts the whole body as JSON.
verification: status: verified tested_at: "2026-11-02" product_version: "okibi 0.2.11; acme-orders 1.0.0" command: "./acme-orders orders list --all --data-source live --no-cache --agent 2>/dev/null | python3 -c \"import json,sys;print(len(json.load(sys.stdin)['results']))\"" expected_result: "7 before and after the dry runs, and requests.log holds only the control GET"
