# Approve the spec

> For agent builds from the terminal. Read the proposed cli-spec.md, then approve it or send it back before anything is built.

The **spec** is `cli-spec.md`, the plan an agent build follows. When a build pauses on it, nothing is built until you approve.

This page is for builds an agent runs, such as `okibi generate --review`. A CLI created in the app builds v1 straight from its OpenAPI spec with no review step. You change it with suggestions and `okibi.yml` instead. See [Create a CLI](https://okibi.ai/docs/guides/create-a-cli.md).

## What the spec is

- A Markdown file kept in the CLI's repository. It records the commands, naming decisions, auth, and the API base URL.
- Every later generation starts from the current spec and updates it, so what you approve now carries forward.
- It is not an OpenAPI file. `okibi generate --spec` takes OpenAPI as a source. `okibi spec` manages `cli-spec.md`.

## What to check

| Check | Look for |
| --- | --- |
| Commands | Every workflow your users need, and nothing they should not have |
| Names | Clear, consistent command groups and required arguments |
| Auth | How a user gets a credential and passes it |
| Pagination | List commands that need more than one page |
| Destructive operations | Deletes and bulk changes, and whether they ask before acting |
| Target endpoint | The base URL is your API, not your docs site |

## Approve or send it back

**In the app**

A paused build shows **Needs review** on the project's **Builds** page, with the summary and what changed. Click **Approve & build** to build, or **Request changes** to open the chat and say what to change. The agent revises the spec and brings it back.

![The Builds page with a build waiting for spec review, showing the summary, what changed, and the Request changes and Approve & build buttons](https://okibi.ai/docs-screens/spec-review.webp)

**In the CLI**

```sh title="Review a paused build"
okibi generate ./my-api --name my-cli --review
okibi spec show my-cli <run-id>
okibi spec approve <run-id>
okibi spec reject <run-id> --feedback "Add pagination to the task list"
```

`--review` stops when the build reaches `awaiting-spec-approval`, prints these commands, and exits. `spec reject` needs `--feedback`. The agent revises, and the build pauses again. You can also approve the same build from the app.

## Which sources can pause for review

| Source | `okibi generate` |
| --- | --- |
| A codebase (GitHub repo or local) | With `--review` or `--spec-only` |
| API docs | Can't pause |
| OpenAPI document | Can't pause |

Without `--review`, `okibi generate` builds straight away. **Regenerate** on a CLI built from API docs or an OpenAPI document also builds without a pause. In the [okibi TUI](https://okibi.ai/docs/cli/tui.md), `/generate` always pauses for review.

## Don't leave it too long

A paused build waits only so long. When its review window closes, the build fails with `spec approval window expired before the reserved build time`. Start a new generation.

To drop a paused build, open its menu (the chevron) on the **Builds** page and pick **Cancel build**. Or run `okibi runs cancel <run-id> --yes`.

## Update the spec without building

```sh
okibi generate ./my-api --name my-cli --spec-only
```

The agent proposes an updated spec and pauses for approval. Approving commits it to the CLI's repository. Nothing is built, and it is free. It needs a codebase source and a CLI that has been generated before.

## Edit the spec yourself

```sh
okibi spec show my-cli > cli-spec.md
okibi spec edit my-cli --file ./cli-spec.md
```

- `spec show` with no run id prints the current approved spec.
- `spec edit` opens `$EDITOR`, or reads `--file`. Use `--file -` for stdin.
- It commits the file to the CLI's repository. It does not build. The next generation starts from your version.
- The CLI must have been generated once. The spec can be 256 KB at most.

In the app, the project's **Spec** page shows the current approved `cli-spec.md`. It is read-only. To change it, describe the change in the chat when you next click **Regenerate**, or use `okibi spec edit`.

## Next steps

- [Builds and chat](https://okibi.ai/docs/guides/runs-and-chat.md): Follow the build after you approve.
- [Review and iterate](https://okibi.ai/docs/guides/review-and-iterate.md): Pick the smallest change once the CLI is built.
- [okibi spec](https://okibi.ai/docs/cli/reference/spec.md): Every spec command and flag.