Handle Nested JSON and Double-Encoded Input 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.
Handle Nested JSON and Double-Encoded Input in an Okibi CLI
Agents often pass structured input as a string inside a string. This guide sends nested JSON, a double-encoded string, broken JSON and a wrong-typed field to a generated Okibi CLI, and shows which are caught by the CLI and which are left to the API.
What you will build
A table of five inputs to orders create --dry-run, with each result and exit code.
--items '<json>' -> CLI parse check -> dry-run preview -> (your API decides the rest)
AI Prompt
Using the generated acme-orders CLI, test how it handles awkward input to `orders create`. Requirements: - Always add `--dry-run --agent` so nothing is created. - Try: valid nested JSON via --items, the same body via --stdin, a double-encoded string, truncated JSON, and a quantity written as a string. - Record each result and exit code. - 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), withACME_ORDERS_API_KEYexported (export ACME_ORDERS_API_KEY=demo-key; the example server calls the same keyACME_API_KEY) and the Acme Orders example API running (ACME_API_KEY=demo-key python3 server.py --port 8099). -
Okibi CLI
0.2.11.
1. Valid nested JSON
./acme-orders orders create --customer-id cus_1 \
--items '[{"product_id":"prd_1","quantity":2}]' --dry-run --agent
The preview shows the item list and the line (dry run - no request sent), followed by a JSON status object ("dry_run": true, "success": false). The exit code is 0. To pass the whole body, use 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
2. A double-encoded string
An agent that serializes twice sends a JSON string that contains JSON:
./acme-orders orders create --customer-id cus_1 \
--items '"[{\"product_id\":\"prd_1\",\"quantity\":2}]"' --dry-run --agent; echo "exit=$?"
Error: --items must be a JSON array exit=1
The CLI refuses it and exits 1, so the agent can correct the encoding and retry.
3. Truncated JSON
./acme-orders orders create --customer-id cus_1 --items '[{"product_id":' --dry-run --agent
Error: parsing --items JSON: unexpected end of JSON input
It exits 1.
4. A field with the wrong type
./acme-orders orders create --customer-id cus_1 \
--items '[{"product_id":"prd_1","quantity":"two"}]' --dry-run --agent
The CLI previews the body as given, with "quantity": "two", and exits 0. It does not check types inside the items. The API is the check that catches it. Run the same command without --dry-run:
./acme-orders orders create --customer-id cus_1 \
--items '[{"product_id":"prd_1","quantity":"two"}]' --agent; echo "exit=$?"
Error: POST /orders returned HTTP 422: {"error": {"type": "invalid_request", "message": "quantity must be an integer of at least 1"}}
exit=5
The example API answers with a structured 422, the CLI reports it as an API error, and exit code 5 marks it. No order is created. A quantity of 0 gets the same 422.
5. A missing required flag
./acme-orders orders create --customer-id cus_1 --agent; echo "exit=$?"
Error: required flag "items" not set exit=2
Summary
| Input | Result | Exit |
|---|---|---|
Valid nested JSON (--items or --stdin) | request preview | 0 |
| Double-encoded string | --items must be a JSON array | 1 |
| Truncated JSON | parsing --items JSON: unexpected end of JSON input | 1 |
"quantity": "two" | previewed as given in a dry run; the API rejects it with a 422 when sent | 0 (dry run), 5 (sent) |
Missing --items | required flag "items" not set | 2 |
Verify the result
./acme-orders orders create --customer-id cus_1 --items '"[{\"product_id\":\"prd_1\",\"quantity\":2}]"' --dry-run --agent >/dev/null 2>&1; echo "exit=$?"
Expected: exit=1.
How it works
The CLI parses --items as JSON and requires an array before it builds the request. Fields inside the objects are passed through unchecked. Required flags are enforced by the command parser (exit 2). Those are the only two checks the CLI makes on this input: the --items value must be a JSON array, and --customer-id and --items must be present.
Common issues
Types inside the items are not checked
The example spec defines each item (OrderItem) as an object with typed fields, and the array as having at least one item. The generated CLI still accepted "quantity": "two" in the dry run, so do not rely on it to check fields inside a nested body. Check them in your API, or in your own wrapper.
Shell quoting hides the problem
Single quotes around the JSON keep the shell from changing it. Use --stdin when the body is large.
verification:
status: verified
tested_at: "2026-10-30"
product_version: "okibi 0.2.11; acme-orders 1.0.0"
command: "./acme-orders orders create --customer-id cus_1 --items '\"[{\\"product_id\\":\\"prd_1\\",\\"quantity\\":2}]\"' --dry-run --agent; echo exit=$?"
expected_result: "Error: --items must be a JSON array, then exit=1"
