# Create a CLI

> Choose a source, name the CLI, and customise its commands with okibi.yml.

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](https://okibi.ai/docs/quickstart.md).

## Choose a source

| Source | In the app | In the CLI |
| --- | --- | --- |
| An OpenAPI document | **OpenAPI spec**: paste its link or drop the file | `--spec ./openapi.yaml` or an `https://` URL |
| Public API docs | **Docs or code**: paste the docs link | `--docs https://docs.example.com/api` |
| A public GitHub repository | **Docs or code**: paste the repo link | `--repo https://github.com/OWNER/REPO` |
| A private GitHub repository | Not available | `--repo https://github.com/OWNER/REPO` |
| A local codebase | Not available | `okibi generate ./path` |

- 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](https://okibi.ai/docs/guides/billing.md).

## 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.

```yaml title="okibi.yml"
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

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

| Flag | What it does |
| --- | --- |
| `--name` | Required. The generated CLI's binary name: the command your users type. |
| `--api-base-url` | The URL the generated CLI calls. |
| `--workspace` | Workspace slug. Falls back to `OKIBI_WORKSPACE`, then your key's home workspace. Ignored for workspace-locked keys. |
| `--review` | Pause for spec approval before building. Codebase sources only. |
| `--spec-only` | Update `cli-spec.md` without building. Codebase sources and existing CLIs only. |
| `--out` | Where to unpack the finished CLI. Defaults to `./<name>`. |
| `--no-pull` | Skip the download. okibi prints the `okibi pull` command instead. |

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](https://okibi.ai/docs/guides/runs-and-chat.md).

`--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](https://okibi.ai/docs/cli/tui.md)). For every flag, see [okibi generate](https://okibi.ai/docs/cli/reference/generate.md).

## 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.

> **Note** A new CLI counts toward your plan's CLI limit. Only successful generations count toward your generation usage. See [Plans and billing](https://okibi.ai/docs/guides/billing.md).

## Next steps

- [Approve the spec](https://okibi.ai/docs/guides/approve-the-spec.md): Review the plan of a terminal build before it builds.
- [Builds and chat](https://okibi.ai/docs/guides/runs-and-chat.md): Follow the build and talk to its agent.
- [Releases and install](https://okibi.ai/docs/guides/releases.md): Choose what your users install.