A build turns a CLI's spec into a CLI and checks it. Creating a CLI, Regenerate, the studio, and the pipeline all start builds. In the terminal, okibi calls a build a run: okibi runs lists them, and <run-id> 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. The CLI is ready to use while they run.
Follow builds
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.
| 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 |
| 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 |
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 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.
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.
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
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.
Click Regenerate in the project's header. It rebuilds from your source and keeps your okibi.yml changes.
- 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-specdoes 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
--dirto 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 <run-id>, shows the output. - The build view offers ways on, such as Try again, Use another source, or Connect GitHub.
okibi status <run-id> --jsonlists them infailure.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.
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.
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 moves a CLI onto the pipeline.
Talk to the agent
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.
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 <run-id> says the corrected artifact is available, run okibi pull <run-id> 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.
Open the project's Builds. Read the Spec review, then click Approve & build, or Ask for changes to tell the agent in its chat.