okibi.ai

Command Palette

Search for a command to run...

Stop Agents from Inventing Flags with 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.

Stop Agents from Inventing Flags with an Okibi CLI

Agents guess flags when they cannot see what a CLI offers. A generated Okibi CLI answers the question directly: agent-context describes every command as JSON, which finds a command from plain words, and okibi clis docs lists each command's real flags. This guide uses all three to answer "how do I cancel an order?" without guessing.

What you will build

A lookup that takes a plain-English task, finds the command, and reads its real usage, with a check that a guessed flag fails.

which "cancel an order"  ->  orders cancel order  ->  okibi clis docs ... orders list  ->  real flags

AI Prompt

Using the generated acme-orders CLI, find the right command for a task without guessing flags.

Requirements:
- Run `acme-orders which "cancel an order" --agent` and read the best match.
- Run `acme-orders agent-context --agent` and list the top-level command names.
- Run `okibi clis docs acme-orders orders list --json` and list the flag names.
- Show that a flag the CLI does not have is rejected.
- 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, logged in.

1. Ask the CLI which command does the job

./acme-orders which "cancel an order" --agent
{
  "matches": [
    { "entry": { "command": "orders cancel order", "description": "Shipped orders cannot be cancelled and return 409.", "group": "orders" }, "score": 7 },
    { "entry": { "command": "orders create", "description": "Create an order", "group": "orders" }, "score": 1 }
  ]
}

The best match is orders cancel order, which is the real command. A third, lower-scoring match (orders get) is trimmed from the sample. To run it: ./acme-orders orders cancel order ord_2 --agent (it fails with a 409 because ord_2 is shipped).

A guess such as orders cancel <id> is wrong. Read the selected command's own help to see its exact usage, including positional arguments:

./acme-orders orders cancel order --help
Shipped orders cannot be cancelled and return 409.

Usage:
  acme-orders orders cancel order <id> [flags]

The <id> is a positional argument, so the full command is ./acme-orders orders cancel order ord_2 --agent.

2. Read the CLI's own description of itself

./acme-orders agent-context --agent

The JSON has schema_version, cli, auth, commands, available_profiles and feedback_endpoint_configured. auth names the environment variable and marks it sensitive. commands lists the whole command tree, 20 top-level commands here, including the built-in ones (doctor, sync, search, feedback, mcp, uninstall and others), each with its use line and, for groups, its subcommands.

3. Read one command's flags from Okibi

okibi clis docs acme-orders orders list --json
{
  "resource": "orders",
  "name": "list",
  "summary": "List orders. Returns array of Order.",
  "usage": "acme-orders orders list [flags]",
  "flags": [
    { "name": "--status", "type": "string", "required": false, "description": "Filter by one order status" },
    { "name": "--customer-id", "type": "string", "required": false, "description": "Customer id" }
  ]
}

The JSON also lists --limit, --cursor and --json, plus an examples array. --all works on orders list (see ./acme-orders orders list --help) but does not appear in the docs JSON. Without a command name, okibi clis docs acme-orders --json lists the CLI's 9 API operations. It does not list the built-in commands. Use agent-context for the full command tree and okibi clis docs for an operation's flags.

4. Confirm a made-up flag is rejected

./acme-orders orders list --state paid --agent; echo "exit=$?"
Error: unknown flag: --state
exit=2

The CLI rejects the unknown flag instead of ignoring it. A wrong enum value is also rejected before any request (--status bogus exits 1), and a missing required flag exits 2 (for example ./acme-orders orders create --customer-id cus_1 --agent prints Error: required flag "items" not set).

Verify the result

./acme-orders which "cancel an order" --agent | python3 -c "import json,sys;print(json.load(sys.stdin)['matches'][0]['entry']['command'])"

Expected: orders cancel order.

How it works

The generator writes a curated feature index into the CLI. which scores your words against it, and agent-context serializes the command tree. okibi clis docs reads the same commands from the release stored at Okibi, so you can check a CLI before installing it.

Common issues

which exits differently depending on the output mode

For a task the CLI cannot do, which "send an invoice by carrier pigeon" in text mode prints Error: no match for ... and exits 2. With --agent or --json it prints {"matches": []} and exits 0. Both are intended. The generated skill's promise that exit code 2 means no confident match holds only in text mode. In agent mode, check the matches array, not the exit code.

The flag list does not show positional arguments

customers get takes an id as an argument, and okibi clis docs shows its required flags as none. Read the usage line for positional arguments.


verification:
  status: verified
  tested_at: "2026-10-30"
  product_version: "okibi 0.2.11; acme-orders 1.0.0"
  command: "./acme-orders which \"cancel an order\" --agent"
  expected_result: "first match is orders cancel order"

Related Articles