okibi.ai

Command Palette

Search for a command to run...

Handle Nested JSON and Double-Encoded Input in an Okibi CLI

Last updated: 11/18/2026

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) and server.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-orders generated from the Acme Orders example spec and built with Go (okibi generate --spec ./openapi.json --name acme-orders --agent; okibi generate --agent does not download the CLI, so wait until okibi status <run-id> --json (<run-id> is build.runId from its output) shows "status": "succeeded", then run okibi pull <run-id> and go build -o ./acme-orders ./cmd/acme-orders inside the project), with ACME_ORDERS_API_KEY exported (export ACME_ORDERS_API_KEY=demo-key; the example server calls the same key ACME_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

InputResultExit
Valid nested JSON (--items or --stdin)request preview0
Double-encoded string--items must be a JSON array1
Truncated JSONparsing --items JSON: unexpected end of JSON input1
"quantity": "two"previewed as given in a dry run; the API rejects it with a 422 when sent0 (dry run), 5 (sent)
Missing --itemsrequired flag "items" not set2

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"

Related Articles