# How Okibi works

> Sources, specs, okibi.yml, builds, and releases. The ideas behind every generated CLI.

Every CLI starts as a **source**, becomes a **spec**, is made by a **build**, and reaches users as a **release**.

In the app, each CLI is a **project**. Its **Overview** draws that path: the source, the spec, and the two things every build makes, the CLI and an MCP server, each with its Skill and Docs. Dashed boxes are not added, built, or turned on yet.

![A project's Overview map: source, spec, the CLI and MCP server with their Skill and Docs, and Identity](https://okibi.ai/docs-screens/project-overview.webp)

## Two CLIs

There are two CLIs in these docs. Keep them apart:

| CLI | Who runs it | What it does |
| --- | --- | --- |
| `okibi` | You, the builder | Creates your CLIs, runs generations, and manages releases |
| Your generated CLI, for example `my-cli` | Your customers and their agents | Calls your product's API |

Your Okibi API key is only for `okibi`. Your generated CLI signs in to your product the way your product expects. The flags in the [Command reference](https://okibi.ai/docs/cli/reference.md) belong to `okibi`, not to your generated CLI.

## Sources

A source is what Okibi reads to learn your API. Each generation uses exactly one:

- **A codebase**, uploaded from a local directory or cloned from GitHub.
- **Public API documentation**, researched from its URL.
- **An OpenAPI document**, from a file or an https URL.

Private repositories need the Okibi GitHub App installed on the account that owns them.

## In the app: v1 and suggestions

The app builds from an OpenAPI spec. Paste its link or drop the file, or give it docs or a public repo and an agent writes the spec first.

1. **v1** builds straight from the spec in about a minute. It is free. When an agent writes the spec from docs or code, that build counts as 1 generation, suggestions included.
2. **Agent ready optimization** then works on login, command names, help text and examples, and workflow commands. Each change is a suggestion you accept or reject. Nothing changes until you accept.
3. Accepted suggestions go into **`okibi.yml`** and ship in a new build, which publishes like any regeneration.

`okibi.yml` lives at the root of the CLI's repository and defines the CLI. When the spec changes, the next build adds its new endpoints as commands and keeps everything in `okibi.yml`, your changes and accepted suggestions alike. See [Create a CLI](https://okibi.ai/docs/guides/create-a-cli.md).

## The spec

In the terminal, `okibi generate` plans the CLI in `cli-spec.md`: every command, its flags, and its output. It is the contract the build follows, so a reviewed spec means no surprises in the CLI.

- `okibi generate --review` pauses for approval. Use `okibi spec approve` or `okibi spec reject --feedback "…"`.
- `okibi generate --spec-only` updates the spec and pauses for approval without building anything.

`--review` and `--spec-only` work for a codebase or a repository. See [Approve the spec](https://okibi.ai/docs/guides/approve-the-spec.md).

> **Note** `okibi generate --spec` takes an OpenAPI document as the source. `okibi spec` reads and approves `cli-spec.md`. The names are close, but they are different things.

## Builds

A build is one generation. A terminal build moves through four stages:

| Stage | What happens |
| --- | --- |
| Generate | An agent researches the source and writes the commands |
| Validate | The CLI is built and checked: build, vet, and shipcheck |
| Package | The built CLI is exercised in live dogfood checks |
| Publish | The release and its installer are published |

A v1 build in the app shows its own steps instead: it reads your spec, writes the CLI, runs lint, builds it for macOS, Linux and Windows, and checks every command.

You can send feedback while a terminal build is working, with `okibi message <run-id> --text "…"` or from its chat in the app. If a build fails, the previous release stays available.

In the terminal, okibi calls a build a run: `okibi runs` lists them, and `<run-id>` names one.

## Releases

A successful build produces a version of the CLI. You choose which version is the official release, who can install it, and where it is hosted. Every release comes with:

- A one-line installer for macOS, Linux, and Windows.
- Generated command docs and a SKILL.md for agents.
- A hosted MCP server.

## Workspaces

Everything above lives in a workspace. Each member is an owner, admin, builder, or tester, and the workspace's plan sets its limits. See [Workspace and members](https://okibi.ai/docs/guides/workspaces.md) and [API keys](https://okibi.ai/docs/guides/api-keys.md).