# Builds > Follow a build, read its logs, publish it, and recover when it fails. A **build** turns a CLI's spec into a CLI and checks it. Creating a CLI, **Regenerate**, the studio, and the [pipeline](https://okibi.ai/docs/guides/pipeline.md) all start builds. In the terminal, okibi calls a build a run: `okibi runs` lists them, and `` names one. ## Steps | Step | What happens | | --- | --- | | Spec | Your spec is read, or an agent writes it from docs or code first | | Codegen | The CLI's code is written | | Lint | The code is linted, alongside the build. Lint only warns | | Build | The CLI is built for macOS, Linux, and Windows | | Test | Every command answers `--help`, and `doctor` runs | From a spec, a build takes about a minute. Then **agent ready optimization** suggests improvements, which you review in [the studio](https://okibi.ai/docs/guides/studio.md). The CLI is ready to use while they run. ## Follow builds **In the app** Open the project and click **Builds**. Each build shows what started it, why it failed, what it made, and its improve jobs. **Load older builds** shows more. A build offers what fits it: **Open build view**, **View logs**, **Try it** (its commands in a simulator), **Connect this version (MCP)**, **Cancel**, and **Delete**. **In the CLI** ```sh okibi runs --cli my-cli okibi status okibi status --cli my-cli okibi runs logs okibi clis docs my-cli --run '#3' okibi runs history my-cli ``` `okibi status` shows a build's steps, how long it takes, and whether it waits for Publish. `runs logs` prints its whole log. `clis docs --run` reads the commands an older build had. `okibi runs` lists recent builds in one workspace (25 by default, 50 at most). `runs history` pages through older ones. | Build | What it means | | --- | --- | | Queued, Building | Waiting to start, or working through the steps | | Built | Finished and checked | | Ready to publish | Built, and waiting for you to [publish it](#publish-a-build) | | Publishing | Being published | | Replaced, Expired | A held build that was never published | | Failed | Stopped. It names the step that failed | | Cancelled | Someone cancelled it | | Needs review | A CLI an older generator built, paused on its spec. See [Older CLIs](#builds-of-older-clis) | ## Publish a build Once a CLI is published, some builds wait for you before they reach anyone: - **Regenerate**, including **Try again** and **Write the spec again**; - a studio change: an accepted improvement or **Save & build**. A [migration](https://okibi.ai/docs/guides/migrate.md) always waits for Publish, even for a CLI that was never published. A CLI's first build, and builds that start themselves when its repository or spec changes, never wait. They go through its [release path](https://okibi.ai/docs/guides/pipeline.md#choose-how-versions-are-released). **In the app** The build view says "Built and checked. Nothing ships until you publish." Click **Publish**. On the release pull request path, Publish adds the build to the release pull request. **In the CLI** ```sh okibi status okibi runs publish ``` In `okibi status --json`, `publish.waits` says the build will wait for Publish, and `publish.available` says it can be published now. A held build waits up to 24 hours, then expires; one whose spec an agent wrote can expire sooner. A newer build replaces it. Publish is refused while a newer build is still running. ## Cancel a build or its improvements **In the app** Click **Cancel** on the build, or **Cancel build** on its build view. To stop only its improvements, click **Cancel improvements**. Nothing they found is kept, and the build stays. **In the CLI** ```sh okibi runs cancel --yes okibi runs cancel-improvements --yes okibi runs delete --yes ``` `runs delete` removes a finished build and its history: a succeeded, failed, or cancelled one. A build that a release depends on can't be deleted. ## Rebuild **In the app** Click **Regenerate** in the project's header. It rebuilds from your source and keeps your `okibi.yml` changes. **In the CLI** ```sh okibi regenerate my-cli okibi regenerate my-cli --rewrite-spec okibi regenerate my-cli --dir ./my-api ``` - When an agent wrote the spec, a rebuild whose docs or code look unchanged reuses that spec. The build view says so, and offers **Write the spec again**. `--rewrite-spec` does the same. It counts as 1 generation, and works once per written spec: it comes back after the docs or code change and a build writes the spec again. - Docs that only load in the browser, such as Redoc or Swagger UI, can't be checked for changes, so Regenerate reuses the spec. Use **Write the spec again** to rebuild it from them. - A CLI built from a local directory rebuilds from the spec its agent wrote. Pass `--dir` to give the agent the directory again. A changed directory writes the spec again. ## When a build fails - The CLI keeps its last good version. Its official release and install command don't change. - The build names the step that failed. **View logs**, or `okibi runs logs `, shows the output. - The build view offers ways on, such as **Try again**, **Use another source**, or **Connect GitHub**. `okibi status --json` lists them in `failure.actions`. - Failed and cancelled builds don't count toward your generation usage. If the copy of the code to your GitHub failed, the build view shows **Not copied**. Try it again from there, or run `okibi clis retry-copy my-cli`. ## Publish edits to the generated repository The CLI's source lives in its own repository. If you commit changes there, publish them as the next version. This doesn't change the official or testing release; choose those in [Releases and install](https://okibi.ai/docs/guides/releases.md). **In the app** On the project's **Overview**, open the **Pipeline** card's **Release** stage. Next to **Repository**, click **Check for changes**. If there are unpublished commits, click **Publish commits**. **In the CLI** ```sh okibi clis changes my-cli okibi clis publish my-cli --commit ``` `clis changes` counts new commits on the default branch and prints the exact publish command. `--commit` stops the publish if new commits landed after you checked. Owners and admins can publish commits. ## Builds of older CLIs CLIs made before the pipeline are built by an agent that plans them in `cli-spec.md`. Their builds have phases instead of steps, and a chat. [Migrating](https://okibi.ai/docs/guides/migrate.md) moves a CLI onto the pipeline. ### Talk to the agent **In the app** Click **Open in studio** on the build to open its chat. Once the build's sandbox is gone, the chat opens read-only with the saved conversation. **In the CLI** ```sh okibi message --text "Add a whoami command" --wait okibi message status okibi attach okibi runs transcript ``` - The agent picks the message up at its next safe point. Messages are 16 KiB at most, and `--file -` reads one from stdin. - `--wait` waits until the agent accepts the message. Accepted doesn't mean done: follow the build with `okibi status`. - Reuse the same `--request-id` and text to retry without sending twice. See [Agent and CI mode](https://okibi.ai/docs/cli/agent-mode.md#retry-safely). - `okibi attach` rejoins a live session in the [TUI](https://okibi.ai/docs/cli/tui.md). `runs transcript` reads the saved chat once the sandbox is gone. ### Repair a finished build Send `okibi message` to a build that succeeded and still has its conversation. The agent repairs that same build and version, at no extra generation charge. When `okibi status ` says the corrected artifact is available, run `okibi pull ` again. Release pins don't change. If the repair fails, the earlier artifact stays. ### A build waiting for its spec A build of an older CLI can be paused on a proposed `cli-spec.md`. It shows **Needs review**, and **Needs you** on the dashboard lists it. **In the app** Open the project's **Builds**. Read the **Spec review**, then click **Approve & build**, or **Ask for changes** to tell the agent in its chat. **In the CLI** ```sh okibi spec show my-cli okibi spec approve okibi spec reject --feedback "Add pagination to the task list" ``` `okibi message` doesn't work on a paused build; use `spec reject --feedback`. To drop the build instead, cancel it. ## Next steps - [The studio](https://okibi.ai/docs/guides/studio.md): Change the CLI, then publish the build. - [The pipeline](https://okibi.ai/docs/guides/pipeline.md): Rebuild on every change, and choose how versions release. - [okibi runs](https://okibi.ai/docs/cli/reference/runs.md): Every okibi runs flag.