Detect Drift Between Your API and Your 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.
Detect Drift Between Your API and Your Okibi CLI
When the API changes and the CLI does not, agents fail on calls that used to work. This guide compares the OpenAPI spec Okibi built from against your current spec, and reads the CLI's own drift status, so you find the gap before an agent does.
What you will build
A drift check that saves the spec Okibi stored, diffs it against your local spec, and lists changed operations.
okibi spec source --out -> stored spec -> compare with local openapi.json -> changed operations okibi clis changes -> commits ahead of the last release
AI Prompt
Using the Okibi CLI, check whether acme-orders has drifted from the API spec. Requirements: - Run `okibi clis changes acme-orders --json` and report `status` and `commitsAhead`. - Save the stored spec with `okibi spec source acme-orders --out <file>` and diff it against ./openapi.json. - Simulate an API change by adding a query parameter to GET /orders in a copy of the spec, and list the operations whose parameters differ from the stored spec. - Do not change the original spec file. - Run the verification step below before finishing.
Prerequisites
-
The Acme Orders example spec,
openapi.json(a fictional orders API). Download it into your working directory:curl -fsSLO https://raw.githubusercontent.com/heterochromatic/okibi-examples/main/acme-orders/openapi.json
-
A generated CLI named
acme-ordersbuilt fromopenapi.json(okibi generate --spec ./openapi.json --name acme-orders --agent). -
Python 3 and Okibi CLI
0.2.11, logged in.
1. Check the CLI's own status
okibi clis changes acme-orders --json
{ "latestVersion": 3, "releaseVersion": "1.0.2", "commitsAhead": 0, "status": "up-to-date" }
This compares the hosted repository with the last release. It reports source commits, not changes in your API. The real output has more fields (baseCommit, headCommit, branch, compareUrl), and the version numbers depend on how many releases your CLI has.
2. Save the spec Okibi built from
okibi spec source acme-orders --out built-from.json
wrote built-from.json (openapi.json, 16188 bytes)
Without --out the command prints the spec. --json prints metadata only (name, size, who wrote it). A CLI built from a linked spec URL keeps no spec file, and the command says so.
3. Diff against your spec
The <( ... ) syntax needs bash or zsh.
diff <(python3 -m json.tool built-from.json) <(python3 -m json.tool openapi.json) && echo IDENTICAL
IDENTICAL
4. Simulate drift and list the changed operations
First make the changed copy. Save this as make_changed.py and run python3 make_changed.py. It adds a created_after query parameter to GET /orders in a copy, and leaves your spec alone:
import json
s = json.load(open("openapi.json"))
s["paths"]["/orders"]["get"]["parameters"].append(
{"name": "created_after", "in": "query", "schema": {"type": "string"}})
json.dump(s, open("openapi.changed.json", "w"), indent=2)
Then compare the parameter names of each operation. This is a demonstration of the idea, not an API compatibility check: it sees names only. Save this one as compare.py and run python3 compare.py:
import json
a = json.load(open("built-from.json")); b = json.load(open("openapi.changed.json"))
def ops(s):
return {(m.upper(), p): sorted(x["name"] for x in o.get("parameters", []))
for p, v in s["paths"].items() for m, o in v.items()
if m in ("get", "post", "patch", "put", "delete")}
oa, ob = ops(a), ops(b)
for k in sorted(set(oa) | set(ob)):
if oa.get(k) != ob.get(k):
print("CHANGED", k, "built:", oa.get(k), "now:", ob.get(k))
print("operations built:", len(oa), "now:", len(ob))
CHANGED ('GET', '/orders') built: ['cursor', 'customer_id', 'limit', 'status'] now: ['created_after', 'cursor', 'customer_id', 'limit', 'status']
operations built: 9 now: 9
Verify the result
Step 3 prints IDENTICAL for the unchanged spec, and step 4 prints exactly one CHANGED line for GET /orders.
How it works
Okibi keeps the spec the CLI was generated from, and okibi spec source reads that stored copy. It reads the CLI's current stored source, not the spec of a release you pick, so it is the right baseline only while no one has replaced the stored spec since the release you care about. Comparing it with your current spec shows what the CLI does not know about yet. The script above compares parameter names only. It does not see changed types, required flags, parameter locations, path-level parameters, $ref targets, request bodies or responses. For real compatibility checking, use an OpenAPI diff tool. To keep a baseline that does not move, save the spec and its hash when you cut each release:
okibi spec source acme-orders --out baseline-1.0.4.json && shasum -a 256 baseline-1.0.4.json
Common issues
clis changes does not see API changes
up-to-date and commitsAhead: 0 mean the CLI repository has no new commits. A changed API shows up only in the spec diff.
Fixing drift needs a rebuild, and not every rebuild uses a generation
okibi regenerate <cli> rebuilds a CLI from its source, and okibi migrate rebuilds a CLI an older generator built. They use your plan differently. Per Okibi's billing guide (https://okibi.ai/docs/guides/billing), migrating is free. A spec-based regenerate reuses the spec for free, and its agent-ready optimization uses a generation only when its agents do any work. Regenerating a CLI an older generator built uses one. Neither command was run in this guide.
A spec URL leaves nothing to diff
For a CLI generated from --spec <url>, spec source keeps no file. Fetch the URL yourself.
verification: status: verified tested_at: "2026-11-02" product_version: "okibi 0.2.11; acme-orders 1.0.2" command: "okibi spec source acme-orders --out built-from.json && python3 compare.py" expected_result: "one CHANGED line for GET /orders, then operations built: 9 now: 9"
