Bundle Many Calls into One Workflow with Sync and Offline Search 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.
Bundle Many Calls into One Workflow with Sync and Offline Search in an Okibi CLI
Agents waste calls when they must page through every resource. Generated Okibi CLIs include a sync command that copies resources into a local database, plus search and workflow status that answer from it. This guide pulls the example API's data once and then answers questions without further API calls.
What you will build
One sync of all three resources, a status summary, and a search served from the local store.
sync -> local SQLite store -> workflow status / search -> answers with "source": "local"
AI Prompt
Using the generated acme-orders CLI, sync the example API once and answer from the local copy. Requirements: - Run `acme-orders sync --agent` and report the total records and resources. - Run `acme-orders workflow status --agent` and report the count per resource. - Run `acme-orders search ord_2 --agent` and report which source answered and the order found. - 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. Sync everything
./acme-orders sync --agent
{"event":"sync_start","resource":"orders"}
{"event":"sync_start","resource":"products"}
{"event":"sync_start","resource":"customers"}
{"event":"sync_complete","resource":"orders","total":7,"duration_ms":6}
{"event":"sync_complete","resource":"customers","total":2,"duration_ms":6}
{"event":"sync_complete","resource":"products","total":3,"duration_ms":6}
{"event":"sync_summary","total_records":12,"resources":3,"success":3,"warned":0,"errored":0,"duration_ms":7}
Each line is one JSON event, so a script can follow progress. The real output also has sync_progress lines, and the sync_complete lines can come in a different order from run to run. The summary shows 12 records across 3 resources.
2. Check what is stored
./acme-orders workflow status --agent
{ "customers": 2, "orders": 7, "products": 3 }
The real output is pretty-printed over several lines.
3. Search the local copy
./acme-orders search ord_2 --agent
This API has no search endpoint. Searching local data.
{
"meta": { "reason": "no_search_endpoint", "resource_type": "search", "source": "local" },
"results": [ { "id": "ord_2", "customer_id": "cus_1", "status": "shipped", "total_cents": 3750 } ]
}
"source": "local" shows the answer came from the stored data. The record also has an items array, omitted here. The example API has no search endpoint, so the CLI falls back to the local store.
4. Prove it works offline
Stop the example API: press Ctrl+C in the terminal where it runs, or kill the process id you saved when you started it. Then ask the CLI again:
./acme-orders search ord_2 --agent 2>/dev/null | python3 -c "import json,sys;d=json.load(sys.stdin);print(d['meta']['source'],[r['id'] for r in d['results']])" ./acme-orders workflow status --agent 2>/dev/null | python3 -c "import json,sys;print(json.load(sys.stdin))" ./acme-orders orders get ord_2 --data-source live --no-cache --agent; echo "exit=$?" ./acme-orders orders get ord_2 --agent
local ['ord_2']
{'customers': 2, 'orders': 7, 'products': 3}
Error: GET /orders/ord_2: Get "http://127.0.0.1:8099/v1/orders/ord_2": dial tcp 127.0.0.1:8099: connect: connection refused
exit=5
warning: API unreachable (connect: connection refused); answering from local data synced just now. Pass --data-source live to fail instead.
{ "meta": { "source": "local", ... }, "results": { "id": "ord_2", ... } }
With the API down, search and workflow status answer from the stored copy, a live read fails with a connection error, and a normal read warns and falls back to local data. sync is what made that possible, and the answers are only as fresh as the last sync. Start the example API again before you continue.
Verify the result
./acme-orders workflow status --agent
Expected: {"customers": 2, "orders": 7, "products": 3} for the untouched example data. If you created orders since, the order count is higher.
How it works
sync fetches every page of each resource and writes it to a SQLite file under ~/.local/share/acme-orders/. search and the workflow commands read that file. Read commands also accept --data-source live|local|auto, and --max-age (default 30 minutes) sets when a hint suggests syncing again.
Common issues
Local data goes stale
The store is a snapshot of the API at the moment of the last sync, not a live view. After the API changes, run sync again. A normal read that falls back to local data warns you and reports how long ago the data was synced. doctor shows the cache status and a hint when sync_state is empty.
The MCP server has a sql tool, the CLI has no sql command
acme-orders sql ... fails with unknown command "sql". The sql tool exists only in the MCP surface.
The sync event lines print to the terminal
They are JSON, one per line. To get only the summary, parse them and keep the line whose event is sync_summary.
verification: status: verified tested_at: "2026-11-02" product_version: "okibi 0.2.11; acme-orders 1.0.0" command: "./acme-orders workflow status --agent" expected_result: "customers 2, orders 7, products 3 for the untouched example data"
