Create a CLI

A new CLI needs a source, a name, and the API base URL it will call. This page covers each choice and its limits. For the shortest path, see the Quickstart.

Choose a source

• Use one source per generation.
• In the terminal, private repositories need the Okibi GitHub App on the account that owns them.
• Repo, docs, and OpenAPI links must be https://, with no username or password in them.
• OpenAPI files are JSON or YAML (.json, .yaml, .yml), up to 50 MiB.
• A local directory is uploaded as one archive, up to 200 MiB compressed. In a git repository, okibi follows your .gitignore. It always skips .git, node_modules, dist, build, target, vendor, .venv, .next, __pycache__, symlinks, and .env files (except ones ending in .example).

Create it in the app

1. Click New CLI on the workspace Overview or the Projects page.
2. Enter a Name: the command your users type.
3. Under Start from, pick one:
   • OpenAPI spec: paste a public link to the spec, or drop a JSON or YAML file.
   • Docs or code: paste an API docs link or a public GitHub repository. An agent writes the OpenAPI spec first.
4. Under Where the code goes, pick an Okibi-hosted private repo, or My GitHub to keep it in a private repo you own. My GitHub is part of Pro.
5. Click Create CLI.

The first version, v1, builds straight from the spec in about a minute, with no review step. v1 from a spec is free; with Docs or code, writing the spec and the improvements that follow count as one generation together, and a rebuild whose docs or code haven't changed reuses the spec for free. Docs that load in the browser (Redoc, Swagger UI) can't be checked for changes, so Regenerate reuses the spec; use Write the spec again to rebuild it from them. You can leave the page: Okibi emails you when it's ready, or if the build stops.

Review suggestions

Once v1 is ready, agent ready optimization works on login, command names, help text and examples, and workflow commands. Each change arrives as a suggestion on the build's ready page, and the project's Overview links there while any wait. Click Accept or Reject, or Accept all.

Your CLI doesn't change until you accept. Accepted suggestions are written into okibi.yml and ship in a new build, which publishes like any regeneration. A rejected suggestion isn't offered again. One optimization counts as one successful generation, and a rebuild where nothing needs improving doesn't run one. See Plans and billing.

Customise it with okibi.yml

okibi.yml sits at the root of the CLI's repository and defines the CLI. Accepted suggestions live in its sections; your own changes go in its human section, and always win.

sections:
  human:
    entries:
      - target: {operation: "GET /invoices"}
        group: billing
        name: ls
      - target: {operation: "DELETE /customers/{id}"}
        enabled: false

• Each command is keyed by its method and path, as in the spec.
• Rename, group, alias, hide, or add examples to a command. Set enabled: false to leave it out.
• Editing an accepted suggestion's entry makes it yours: Okibi keeps it and never rewrites it.
• The next build applies it. Regenerate rebuilds from your spec and keeps everything in okibi.yml.

When your spec changes

The next build turns new endpoints into commands with default names, and keeps everything in okibi.yml. When Okibi watches your spec link, a change rebuilds the CLI on its own, and agent ready optimization improves only what the change touched.

If you edited the generated code and the new code no longer fits your edit, Okibi carries the edit over for you and the build says so.

Which workspace it lands in

The app creates the CLI in the workspace where you clicked New CLI. To create one in another workspace, switch to it first. From the terminal, pass --workspace acme to okibi generate.

Create it in the CLI

okibi generate --repo https://github.com/OWNER/REPO --name my-cli --api-base-url https://api.example.com --workspace acme

okibi prints the run id, streams each stage, and unpacks the CLI when the build succeeds. Ctrl-C only stops watching: the build keeps going, and okibi runs --cli my-cli finds it again. See Builds and chat.

--repo has no branch option and builds the default branch. To build another branch, use the app. To shape commands in a chat first, run okibi and type /new (The okibi TUI). For every flag, see okibi generate.

Name rules

• 1 to 64 lowercase letters, numbers, or hyphens.
• Starts with a letter. Ends with a letter or a number.
• okibi is reserved.
• One name per workspace. If my-cli already exists there, the build updates that CLI instead of creating a new one.

Set the API base URL

This section is for okibi generate. The base URL is where the generated CLI sends requests, such as https://api.example.com. It is not your docs site.

• Start with http:// or https://. No username, password, query string, or # fragment. 2 KB at most.
• Leave it empty to let the agent detect it from the source.
• It is recorded in cli-spec.md, so later generations keep it.
• Passing --api-base-url again on an existing CLI updates the stored URL.

To point a released CLI at a new endpoint without regenerating, run okibi clis endpoint set my-cli https://api.example.com. It publishes a config-only release.

Next steps