Generate an Agent-Ready CLI from an OpenAPI Spec with the 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.
Generate an Agent-Ready CLI from an OpenAPI Spec with the Okibi CLI
okibi generate --spec takes an OpenAPI document and produces a Go CLI for that API, with JSON output, stable exit codes and a dry-run mode for writes. The build stages (spec, codegen, lint, build, test) in this guide finished in 25 seconds, and the whole run took about 32 seconds.
What you will build
A CLI named acme-orders generated from the spec of a small orders API (9 operations across orders, customers and products), built locally and exercised with reads, pagination, errors and a dry-run write.
openapi.json -> okibi generate -> okibi pull -> go build -> acme-orders binary -> Acme Orders API
AI Prompt
Using the Okibi CLI, generate a CLI from the Acme Orders OpenAPI spec and show that agents can use it safely. Requirements: - Start the Acme Orders API first (`ACME_API_KEY=demo-key python3 server.py --port 8099`). It listens on http://127.0.0.1:8099/v1 and expects the key in the X-API-Key header. - Run `okibi generate --spec ./openapi.json --name acme-orders --out ./acme-orders --agent`. The API address comes from the `servers` entry in the spec, so there is no base-URL flag. - Generation runs in the Okibi cloud through five stages: spec, codegen, lint, build and test. With `--agent` the command prints one JSON status when the build settles. - `--name` must be kebab-case. `--spec` accepts a local file or an https URL. - In `--agent` or `--json` mode `okibi generate` does not download the CLI. A manual pull is expected: take the run id from `build.runId`, wait until `okibi status <run-id> --json` shows `"status": "succeeded"` (stop with the failure details if it does not), then run `okibi pull <run-id> --out ./acme-orders`. - The generated project is Go. Build it with `go build -o ./acme-orders ./cmd/acme-orders` from inside the project. - `--agent` on the generated CLI sets `--json --compact --no-input --no-color --yes`. - Set `ACME_ORDERS_API_KEY` to the API key. Set `ACME_ORDERS_BASE_URL_OVERRIDE` only to override the address stored in the CLI. - Exit codes: an invalid `--status` value exits 1 before any request is sent, a missing flag or argument exits 2, a resource that does not exist exits 3, a missing or invalid key exits 4, and an error returned by the API exits 5. Rate limiting exits 7. - `orders list` returns 3 orders per page by default and reports the next cursor under `meta.pagination`. `--limit` and `--cursor` page through results. - Write commands accept `--dry-run`, which prints the request and sends nothing. - Check reads with `--data-source live --no-cache` so a cached answer cannot stand in for the API's. - 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
-
The Okibi CLI installed and logged in:
curl -fsSL https://okibi.ai/install | sh, thenokibi auth loginand approve the browser prompt. Version tested:okibi 0.2.11. For CI or a sandbox, create a workspace-locked key withokibi keys create --name <label>and set it asOKIBI_API_KEYinstead. The key is printed once, so store it as a secret. -
Go 1.26 or later to build the generated CLI (the generated
go.moddeclaresgo 1.26). Tested with Go 1.27.0. -
Python 3 to run the example API.
-
About the two example files you downloaded above:
openapi.jsonis the spec, andserver.pyis an in-memory implementation of it using only the Python standard library. The spec describes these operations, all under/v1and all requiring theX-API-Keyheader, and listshttp://127.0.0.1:8099/v1as its server:Operation Method and path List orders ( status,customer_id,limit,cursor)GET /ordersCreate an order ( customer_id,items)POST /ordersGet or update an order GET,PATCH /orders/{id}Cancel an order (shipped orders return 409) POST /orders/{id}/cancelList or create customers, get one GET,POST /customers,GET /customers/{id}List products GET /products -
Network access to
okibi.ai. -
Room for one more CLI project.
okibi billing status --agentshows how many CLI projects and generations you have left. On the Free plan used for this guide it showed 1 CLI project and 5 successful generations a month.
Note: JSON samples below are trimmed to the fields relevant to each step.
1. Start the example API
ACME_API_KEY=demo-key python3 server.py --port 8099
Acme Orders mock on http://127.0.0.1:8099 (X-API-Key: demo-key)
Leave it running in its own terminal. To run it in the background instead, start it with & and save its process id, and stop that process (and only that one) when you are done:
ACME_API_KEY=demo-key python3 server.py --port 8099 & SERVER_PID=$! # ... later: kill $SERVER_PID
2. Generate the CLI
okibi generate \ --spec ./openapi.json \ --name acme-orders \ --out ./acme-orders \ --agent
The command uploads the spec, follows the build and prints one JSON status once it settles. The fields that matter:
{
"build": {
"runId": "<run-id>",
"status": "running",
"phase": "ready",
"settled": true,
"cli": { "name": "acme-orders", "publishTarget": "hosted" },
"checks": [
{ "id": "codegen", "label": "Codegen", "state": "done", "note": "9 commands" },
{ "id": "lint", "label": "Lint", "state": "done", "note": "no issues" },
{ "id": "build", "label": "Build", "state": "done" },
{ "id": "test", "label": "Test", "state": "done", "note": "40 commands checked" }
]
},
"cliCreated": true
}
The run id is build.runId in this JSON. okibi runs --agent (next step) shows the same value as id. Use it wherever this guide says <run-id>.
"status": "running" refers to the run, which is still finishing. The build, test and 9 commands are already done, and the lint check is done with no issues. Okibi then starts an agent-ready optimization that generates suggestions for login, command names, help and examples, and workflow commands. Those suggestions are proposals. Nothing in the CLI changes until you accept them in the studio, so the v1 CLI you build in this guide is the one that was already built.
3. Check the run
okibi runs --agent
[
{
"cliName": "acme-orders",
"status": "succeeded",
"number": 1,
"durationMs": 31582,
"version": 1,
"releaseVersion": "1.0.0"
}
]
4. Wait for the run, then pull and build the CLI
In --agent or --json mode, okibi generate deliberately does not download the CLI, so there is no acme-orders directory yet. A manual pull is expected. Wait until the run has succeeded, then pull it by run id:
RUN=<run-id> # build.runId from step 2 for i in $(seq 1 60); do s=$(okibi status "$RUN" --json | python3 -c "import json,sys;print(json.load(sys.stdin)['status'])") [ "$s" = "succeeded" ] && break sleep 5 done echo "run status: $s"
run status: succeeded
If the run does not reach succeeded, okibi status "$RUN" --json shows the failure and the next commands to try (failure.actions). succeeded means the build is finished and the source can be pulled. The optimization suggestions from step 2 are tracked separately.
okibi pull "$RUN" --out ./acme-orders --agent cd acme-orders go build -o ./acme-orders ./cmd/acme-orders ./acme-orders --version
generated CLI unpacked into ./acme-orders acme-orders 1.0.0
The command groups follow the API: orders, customers and products, plus built-in doctor, sync, search, workflow, feedback, profile, which and mcp commands. acme-orders --help lists them all.
5. Point the CLI at the API
export ACME_ORDERS_API_KEY=demo-key ./acme-orders doctor --agent
{
"api": "host reachable (HTTP 404 at /)",
"auth": "configured",
"auth_source": "env:ACME_ORDERS_API_KEY",
"base_url": "http://127.0.0.1:8099/v1",
"config": "ok",
"credentials": "present, not verified. Run `acme-orders customers list` to confirm the token works end-to-end.",
"version": "1.0.0"
}
base_url comes from the spec with no environment variable set. doctor reports HTTP 404 at / because the example API has no route at its root. The host is reachable. To use a different address, set ACME_ORDERS_BASE_URL_OVERRIDE or pass --base-url.
6. Read and page through orders
./acme-orders orders list --limit 2 --data-source live --no-cache --agent
{
"meta": {
"pagination": { "next_cursor": "2" },
"source": "live"
},
"results": [
{ "id": "ord_1", "customer_id": "cus_2", "status": "paid", "total_cents": 2500 },
{ "id": "ord_2", "customer_id": "cus_1", "status": "shipped", "total_cents": 3750 }
]
}
--data-source live --no-cache makes the CLI ask the API and skip the response cache, so "source": "live" is a real API answer. stderr also prints {"event":"truncated","hint":"pass --all to fetch every page"}. Pass the cursor to get the next page:
./acme-orders orders list --limit 2 --cursor 2 --data-source live --no-cache --agent
The response holds ord_3 and ord_4 and a next_cursor of "4". --status shipped returns ord_2 and ord_6 with "next_cursor": null.
7. Check error behavior
./acme-orders orders list --status bogus --agent; echo "exit=$?"
./acme-orders orders get ord_999 --agent; echo "exit=$?"
./acme-orders orders create --customer-id cus_9 --items '[{"product_id":"prd_1","quantity":2}]' --agent; echo "exit=$?"
env -u ACME_ORDERS_API_KEY ./acme-orders orders list --agent; echo "exit=$?"
Error: invalid value "bogus" for --status: must be one of [pending paid shipped cancelled]
exit=1
Error: GET /orders/ord_999 returned HTTP 404: {"error": {"type": "not_found", "message": "order ord_999 not found"}}
hint: not found. Check the ID or other path values (a resource's list command, where it has one, shows valid ones) and the base URL ('acme-orders doctor' shows it)
exit=3
Error: POST /orders returned HTTP 422: {"error": {"type": "invalid_request", "message": "customer_id must reference an existing customer"}}
exit=5
Error: GET /orders returned HTTP 401: {"error": {"type": "unauthorized", "message": "Missing or invalid X-API-Key header"}}
hint: check your API key. Set your API key with: export ACME_ORDERS_API_KEY="your-token-here"
Run 'acme-orders doctor' to check auth status.
exit=4
With the key unset, the 401 is reported as an authentication problem and exits 4. The CLI uses these exit codes: 0 success, 1 input rejected by the CLI before any request, 2 a missing flag or argument, 3 a resource that does not exist, 4 authentication, 5 an error returned by the API, 7 rate limited, 10 a configuration error. A missing id (./acme-orders orders get with no id) exits 2. A well-formed id that does not exist (ord_999) exits 3.
8. Preview a write with --dry-run
./acme-orders orders create \
--customer-id cus_1 \
--items '[{"product_id":"prd_1","quantity":2}]' \
--dry-run --agent
stderr shows the request, and stdout shows a JSON status object:
POST http://127.0.0.1:8099/v1/orders
Body:
{ "customer_id": "cus_1", "items": [{ "product_id": "prd_1", "quantity": 2 }] }
X-API-Key: ****-key
(dry run - no request sent)
{ "action": "post", "data": { "dry_run": true }, "dry_run": true, "path": "/orders", "resource": "orders", "status": 0, "success": false }
"success": false and "status": 0 mean nothing was sent, not that the command failed. The key is masked in the preview.
Verify the result
./acme-orders orders list --status bogus --agent >/dev/null 2>&1; echo "exit=$?" ./acme-orders orders list --limit 2 --data-source live --no-cache --agent 2>/dev/null | python3 -c "import json,sys;d=json.load(sys.stdin);print([o['id'] for o in d['results']], d['meta']['source'])"
Expected: exit=1, then ['ord_1', 'ord_2'] live. The first check is rejected by the CLI before any request, so it does not depend on the API's data. The second asks the API and checks the values it returns. A missing id exits 2, an id that does not exist exits 3, and a rejected create exits 5.
How it works
okibi generate uploads the spec to the Okibi cloud, which reads the operations, writes a Go project, lints it, builds it for macOS, Linux and Windows, and runs every command's --help plus doctor as a test. The result is release 1.0.0. The generated CLI calls the API directly from your machine, using the first servers entry of the spec unless ACME_ORDERS_BASE_URL_OVERRIDE or --base-url overrides it. The CLI checks the --status enum before any request is sent. It does not check numeric bounds or nested fields: --limit 500 reaches the API, which answers HTTP 400, and the CLI exits 5.
Common issues
A manual pull is expected
In --agent or --json mode, okibi generate and okibi regenerate do not download the CLI. This is by design, not a timing problem. Take the run id from build.runId, wait until okibi status <run-id> --json shows succeeded, then run okibi pull <run-id> --out ./acme-orders. okibi runs --agent lists the same run with its id.
The API address cannot be set with a flag
okibi generate has no --api-base-url flag. Put the address in the spec's servers list before generating, or override it on the built CLI with ACME_ORDERS_BASE_URL_OVERRIDE or --base-url. The cloud cannot reach 127.0.0.1, and the build still passed against this local address. So test the built CLI against your own running API as in steps 5 to 8.
The override variable name
On this build the override is ACME_ORDERS_BASE_URL_OVERRIDE (or --base-url). ACME_ORDERS_BASE_URL is ignored. Point it at a dead port with --data-source live to see which name your build reads.
Lint reports a warning
For this spec the lint check reports done with no issues. If your lint check shows warning with a count of issues, the build and test checks can still pass. The status output does not list the issues.
Only one status per call
--status shipped,pending is rejected with the same message as bogus and exits 1. Call the command once per status.
Lists return three orders by default
orders list returns 3 orders per page unless you pass --limit, and prints a truncated hint on stderr when more pages exist. Use --cursor with the next_cursor value, or --all to fetch every page. --limit above 100 is rejected by the API (HTTP 400, exit 5), not by the CLI.
Which actions use a generation
The Free plan includes 5 successful generations a month. okibi billing status --agent shows how many you have used, and Settings > Plan in the Okibi web app shows when the count resets. A build from an OpenAPI spec, as in this guide, is free. The agent-ready optimization that follows it uses one generation when its agents do any work: on the test account the used count went from 3 to 4 after this build. Builds from docs or a repository use one. Migrating a CLI an older generator built is free. Okibi's billing guide (https://okibi.ai/docs/guides/billing) has the full table.
This guide creates one CLI project. If okibi billing status --agent shows none left, free one up on your own terms (okibi clis delete <name> needs a human terminal, and it is permanent) or use a workspace with room. Do not delete a CLI you still use.
verification: status: verified tested_at: "2026-11-02" product_version: "okibi 0.2.11; acme-orders 1.0.0" command: "./acme-orders orders list --status bogus --agent >/dev/null 2>&1; echo exit=$?; ./acme-orders orders list --limit 2 --data-source live --no-cache --agent" expected_result: "exit=1, then ord_1 and ord_2 with source live"
