# The pipeline

> Rebuild a CLI whenever its source changes, choose how new versions release, and handle release pull requests.

The **pipeline** is how a change becomes a release. It has five stages:

| Stage | What it covers |
| --- | --- |
| Source | What the CLI builds from, and whether a change rebuilds it on its own |
| Build | The latest build. Every version builds in its own sandboxes, for macOS, Linux, and Windows |
| Checks | Every command answers `--help` and `doctor` runs before a build can be released. Lint only warns |
| Release | Where the code lives, and how a new version reaches it |
| Publish | The Okibi installer, and optionally npm and Homebrew |

**In the app**

Open the project's **Overview**. The **Pipeline** card shows each stage. Click a stage to see why it reads as it does and to set it up.

**In the CLI**

```sh
okibi clis pipeline status my-cli
```
It shows each stage, why it reads as it does, and its setup. In the TUI, run `/pipeline my-cli`.

Owners, admins, and builders can change the Source and Release settings. npm, Homebrew, publishing commits, and approving a major release need an owner or admin.

## Rebuild on every push

For a CLI built from a GitHub repository, **auto-generate** rebuilds it whenever its branch changes. A linked repository rebuilds on every push. A public repository pasted by its link is checked every hour, and rebuilds when it has a new commit.

**In the app**

In the **Source** stage, click **Change** next to **Auto-generate**, and turn on **Rebuild on pushes to** the repository. The switch saves at once. To watch another branch, change **Branch** and click **Save**. For a public repository pasted by its link, click **Watch**: the dialog is **Watch for changes (hourly)**.

**In the CLI**

```sh
okibi clis pipeline auto-generate my-cli on --branch main
okibi clis pipeline auto-generate my-cli off
```
With no `--branch`, `on` keeps the branch already watched, or watches the CLI's source branch, or the repository's default branch.

- Every build, even one you start by hand, builds this branch and counts toward your plan's limit. For a pasted public repository, an hourly check that finds no new commit costs nothing.
- When a watch pauses, or can no longer read its branch, save it again to take it over and resume. From the terminal, run `on` again with no `--branch`.

## Rebuild when the spec changes

For a CLI built from an OpenAPI link, Okibi can check the link and rebuild when the spec changes. Only changes to operations, parameters, bodies, auth, or servers start a build.

**In the app**

In the **Source** stage, click **Change** next to **Auto-generate**. Turn on **Regenerate when the OpenAPI spec changes**, and pick how often to **Check**: **Every hour**, **Every 6 hours**, or **Every day**. **Check now** checks it right away.

**In the CLI**

```sh
okibi clis pipeline spec-watch my-cli on --every 6h
okibi clis pipeline spec-watch my-cli check
okibi clis pipeline spec-watch my-cli off
```
`on` fetches the spec once and anchors the watch to it. `check` asks for a check now, at most once a minute.

When a rebuild finds new endpoints, it adds them as commands and keeps everything in `okibi.yml`. Agent ready optimization then improves only what the change touched.

## Choose how versions are released

The first publish always goes straight to the repository. After it, each new version takes the CLI's **release path**:

| Path | What happens |
| --- | --- |
| **Push to default branch** | Each build goes straight to the default branch, and you choose the official version. |
| **Release pull request** | Builds collect in one release pull request. Merging it, or pushing a new version to the default branch, releases and tags it. |

Until someone chooses, a CLI uses a release pull request while auto-generate or the spec watch is on.

**In the app**

In the **Release** stage, open **How it releases** and pick **Push to default branch** or **Release pull request**.

**In the CLI**

```sh
okibi clis pipeline release-path my-cli direct
okibi clis pipeline release-path my-cli pull-request
```

An open release pull request stays the way out until it's merged or closed.

## Handle a release pull request

The **Release PR** row shows the open pull request. Click **Open** to see it on GitHub. When it needs a person, the button is **Details**, which shows what it holds and what it needs from you. **Needs you** on the dashboard also lists a release pull request that waits on a person.

- **Breaking changes.** A release pull request whose commands changed incompatibly releases as a minor version until an owner or admin approves a major one. Click **Release as major**, or run `okibi clis pipeline approve-major my-cli`.
- **A failed release.** When a merged release pull request, or a version pushed to the default branch, didn't release, click **Retry release**, or run `okibi clis pipeline retry-release my-cli`. When both failed, add `--pull-request` or `--push`.

## A version pushed to the default branch

On the release pull request path, you can also release by pushing a version bump straight to the published default branch. It releases like a merged release pull request. The **Release** stage's **Pushed version** row shows it; if it didn't release, **Details** offers **Retry release**, or run `okibi clis pipeline retry-release my-cli --push`.

## Where the code lives and where it's published

The **Release** stage also holds **Repository** (where the code lives) and the **Official version**. The **Publish** stage holds the Okibi installer and **npm and Homebrew**. See [Releases and install](https://okibi.ai/docs/guides/releases.md#choose-where-the-source-code-lives) and [npm and Homebrew](https://okibi.ai/docs/guides/package-managers.md).

- [Builds](https://okibi.ai/docs/guides/builds.md): Follow a build and publish it.
- [okibi clis pipeline](https://okibi.ai/docs/cli/reference/clis.md#okibi-clis-pipeline): Every pipeline command and flag.