okibi.ai

Command Palette

Search for a command to run...

Bundle Many Calls into One Workflow with Sync and Offline Search 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.

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) 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. 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"

Related Articles