okibi.ai

Command Palette

Search for a command to run...

Generate a Command Reference from 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.

Generate a Command Reference from an Okibi CLI

A docs team that hand-writes a CLI reference falls behind. okibi clis docs returns every command's summary, usage and flags as JSON, so a small script can rebuild a reference page each time a release ships. This guide writes that script and checks its output.

What you will build

A Python script that turns okibi clis docs acme-orders --json into a Markdown reference page with one section per API command: a corrected summary, the usage line (with positional arguments), the flags and an example.

okibi clis docs <cli> --json  ->  gen_docs.py (+ openapi.json for return types)  ->  REFERENCE.md

AI Prompt

Using the Okibi CLI, generate a Markdown command reference for acme-orders.

Requirements:
- Read the commands with `okibi clis docs acme-orders --json`, and each command's detail with `okibi clis docs acme-orders <resource> <name> --json`.
- For each command write the full command as a heading, a one-line summary, the usage line (it shows positional arguments such as `<id>`), a table of flags with required or optional, and the example.
- Take what each command returns from the OpenAPI spec, and replace the generated "Returns ..." text, because some of it is wrong.
- State which commands the page covers.
- Count the sections and compare with the number of commands.
- 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-orders (okibi generate --spec ./openapi.json --name acme-orders --agent).

  • Python 3 and Okibi CLI 0.2.11, logged in.

1. Write the script

Save it as gen_docs.py in the folder that contains openapi.json. The okibi clis docs listing covers the CLI's nine API operations. It joins a command's parts and skips any that are empty, because the products command has no resource part. The script reads what each operation returns from the spec, because Okibi's generated summaries say Returns array of OrderItem for four commands where the spec returns an Order.

import json, re, subprocess, sys

cli = sys.argv[1]
spec = json.load(open("openapi.json"))

def okibi_docs(*args):
    return json.loads(subprocess.check_output(["okibi", "clis", "docs", cli, *args, "--json"]))

# Which spec operation each command runs, and what that operation returns.
OPERATIONS = {
    "orders list": "listOrders", "orders create": "createOrder", "orders get": "getOrder",
    "orders update": "updateOrder", "orders cancel order": "cancelOrder",
    "customers list": "listCustomers", "customers create": "createCustomer",
    "customers get": "getCustomer", "products": "listProducts",
}
RETURNS = {}
for path, item in spec["paths"].items():
    for method, op in item.items():
        if not isinstance(op, dict) or "operationId" not in op:
            continue
        for code, resp in op["responses"].items():
            if code.startswith("2"):
                ref = resp.get("content", {}).get("application/json", {}).get("schema", {}).get("$ref", "")
                name = ref.split("/")[-1]
                if name:
                    RETURNS[op["operationId"]] = (f"a page of {name[:-4]}s" if name.endswith("Page") else f"the {name}")

print(f"# {cli} command reference\n")
print("This page covers the CLI's API operations. It does not cover the built-in commands "
      "(`doctor`, `sync`, `search`, `feedback`, `mcp` and others); run `" + cli + " --help` for those.\n")
for c in okibi_docs()["commands"]:
    name = " ".join(p for p in (c["resource"], c["name"]) if p)
    summary = re.sub(r"\s*Returns .*$", "", c["summary"]).rstrip()
    returns = RETURNS.get(OPERATIONS.get(name, ""), None)
    if returns:
        summary += f" Returns {returns}."
    detail = okibi_docs(*name.split())
    print(f"## `{cli} {name}`\n\n{summary}\n")
    print(f"```text\n{detail['usage']}\n```\n")
    flags = [f for f in detail["flags"] if f["name"] not in ("--json", "--stdin")]
    if flags:
        print("| Flag | Type | Required | Description |\n|---|---|---|---|")
        for f in flags:
            print(f"| `{f['name']}` | {f['type']} | {'yes' if f['required'] else 'no'} | {f['description']} |")
        print()
    for ex in detail.get("examples", []):
        print(f"Example: `{ex['command']}`\n")

2. Run it

python3 gen_docs.py acme-orders > REFERENCE.md
grep -c '^## ' REFERENCE.md
9

The start of the page:

# acme-orders command reference

This page covers the CLI's API operations. It does not cover the built-in commands (`doctor`, `sync`, `search`, `feedback`, `mcp` and others); run `acme-orders --help` for those.

## `acme-orders customers create`

Create a customer. Returns the Customer.

```text
acme-orders customers create [flags]
```

| Flag | Type | Required | Description |
|---|---|---|---|
| `--email` | string | yes | Email |
| `--name` | string | yes | Name |

Example: `acme-orders customers create --email <email> --name <name> --json`

The nine sections are customers create/get/list, orders create/get/list/update, orders cancel order and products. Generated command names can change when a CLI is regenerated. The usage line of customers get is acme-orders customers get <id> [flags], so the page shows the required id, which a flag table alone would hide.

3. Check the summaries

The generated summary for orders create reads Create an order. Returns array of OrderItem. The spec says a successful create returns an Order, and so do orders get, orders update and orders cancel order. After the script runs, those four read Returns the Order. Check the other five against your spec as well: for example, customers list now reads Returns a page of Customers., from the spec's CustomerPage.

grep -A2 '^## `acme-orders orders' REFERENCE.md | grep -c 'Returns the Order'
4

Verify the result

okibi clis docs acme-orders --json | python3 -c "import json,sys;print(len(json.load(sys.stdin)['commands']))"
grep -c '^## ' REFERENCE.md
grep -c 'array of OrderItem' REFERENCE.md

Expected: 9, 9 and 0. The first two say that every command has a section. The last says the wrong summaries are gone (grep -c exits 1 when it counts zero lines).

How it works

okibi clis docs <cli> lists every API command with its summary, usage and flags. With a command name it adds that command's examples. The script calls it once for the list and once per command, and reads the spec for what each operation returns. --run <run> reads the commands an older build had and returns a different JSON shape: {runId, number, current, snapshot: {cliName, commands}}.

Common issues

The flag table leaves out --json and --stdin

Every command accepts them, so the script drops them from each table to keep the page short. --all works on orders list and does not appear in the docs JSON either.

The mapping from commands to spec operations is written by hand

The OPERATIONS table in the script lists the nine commands. If you regenerate the CLI and a command name changes, update it, or the summary keeps Okibi's wording.

Summaries can be wrong

Four of the nine summaries were wrong here. The script replaces what each command returns with what the spec says, and the description before it ("Shipped orders cannot be cancelled and return 409.") comes from the spec too.

Running it on every release is a separate step

The script needs only an Okibi login and the spec, so it can run in a CI job after a release. Nothing in this guide installs that job. Run the script by hand, or add it to your own pipeline.


verification:
  status: verified
  tested_at: "2026-11-02"
  product_version: "okibi 0.2.11; acme-orders 1.0.4"
  command: "python3 gen_docs.py acme-orders > REFERENCE.md; grep -c '^## ' REFERENCE.md; grep -c 'array of OrderItem' REFERENCE.md"
  expected_result: "9, then 0 (the wrong summaries are replaced)"

Related Articles