Find the symptom or message you see. okibi prints errors from the Okibi API as api <status>: <message>.
okibi: command not found
On macOS and Linux, the installer links okibi into ~/.local/bin. When that folder is not on your PATH, the installer prints a NOTE with the line to add to your shell profile:
export PATH="$HOME/.local/bin:$PATH"Open a new terminal and run okibi --version. If you set OKIBI_BIN_DIR when you installed, use that folder instead.
On Windows, the installer adds okibi to your user PATH. Restart your shell to pick it up.
A generated CLI installs into the same place, under its own name, such as my-cli.
Not logged in or wrong workspace
See who you are logged in as, your default workspace, and the workspaces you belong to:
okibi auth status okibi workspaces
| You see | What to do |
|---|---|
An error that starts with not logged in | Run okibi auth login. |
api 401: unknown or revoked api key | The key was revoked. Log in again, or replace OKIBI_API_KEY. |
workspace not found | Check the slug in okibi workspaces. Testers see this too, because their role can't build CLIs. |
this API key is locked to its workspace and cannot target another | The key is locked to one workspace. Use a key made for the workspace you want. |
OKIBI_API_KEY wins over your saved login. If an old key is set in your shell or CI job, okibi uses that one.
To use another workspace, add --workspace acme to the command or set OKIBI_WORKSPACE=acme.
Login on a remote machine
Browser login needs a browser on the same machine. Over SSH, and on Linux without a display, okibi auth login switches to a device code on its own. To force it:
okibi auth login --device-codeokibi prints a code and a URL. Open the URL on any device, confirm the code, and the terminal continues. If you see login code expired or login timed out, run the command again.
For CI, skip the browser and use an API key. See Keys for CI.
Repository missing
Private repositories need the Okibi GitHub App on the account that owns them, with access to that repository.
- Click Repos in the sidebar, then click Sync.
- Still missing? Open Settings, then Account. In the GitHub card, click Manage on GitHub next to the account and give the app access to the repository. No account listed? Click Connect GitHub.
- Go back to Repos and click Sync again.
If GitHub can't be reached, okibi repos shows your saved list and warns GitHub could not be reached; showing saved repositories. Run okibi repos to retry sync. If a command fails with github-connection-required, run okibi auth github to reconnect.
Build is waiting for approval
A build with the status awaiting-spec-approval (Needs review in the app) is paused, not failed. It waits for you to approve or reject its proposed spec. Only agent builds started with okibi generate --review or --spec-only pause like this. A CLI created in the app never does.
Open the project and click Builds. Click Approve & build to build, or Request changes to tell the agent what to change.
okibi message doesn't work on a paused build. It returns run is awaiting spec approval; use okibi spec reject --feedback to revise it. See Approve the spec.
Build failed
okibi generate ends with run <run-id> failed and the reason, then prints the last lines of output. To look again later:
okibi status <run-id> okibi status <run-id> --json
--json includes logTail, the last lines of the build's log. In the app, open the project's Builds: a failed build shows its reason, and its menu has View logs.
If a build fails, the previous release stays available. To try again, start a new build: click Regenerate on the CLI's page, or run okibi generate again with the same --name. A failed build can't take messages; okibi returns this run cannot accept messages; use a successful or active run.
Feedback sent but nothing changed
A delivered message means the agent accepted the instruction, not that the change is finished. Check the message, then the build:
okibi message status <run-id> <message-id> okibi status <run-id>
- Feedback on a finished build reopens the same build as a repair. Its run ID and version stay the same.
- When the repair succeeds, run
okibi pull <run-id>again to get the corrected CLI. - If the repair fails or is cancelled, the previous result stays available, and
okibi statussays so. - If you see
a newer run exists for this CLI; send feedback to its run ID instead, send it to the newest build.
To retry a send safely, reuse the same --request-id and the same text. See Builds and chat.
Can't download or install
okibi pull only works for a build that succeeded. For any other build you get an error such as api 409: run is failed, artifact not ready.
When your users can't install the CLI, check its install state and releases:
okibi clis hosting status my-cli okibi clis releases my-cli
| You see | What to do |
|---|---|
Official release: none | Select one with okibi clis release set my-cli --run <run-id>. |
404 from the install URL | The plain install link works only when visibility is public. With workspace visibility, each member gets their own command from okibi clis hosting status. |
no my-cli build published for linux-arm64 yet | The official release has no build for that platform. Select another release. |
An error that starts with unsupported OS | The sh installer is for macOS and Linux. On Windows, add .ps1 to the install URL and run it in PowerShell. |
If okibi update says this installation predates automatic updates; reinstall once from https://okibi.ai/install, run the installer again. See Releases and install.
The generated CLI's API calls fail
Your generated CLI calls your API, not Okibi. First, check the base URL compiled into the official release:
okibi clis endpoint status my-cli okibi clis endpoint set my-cli https://api.example.com
endpoint set publishes a config-only release. It doesn't run a new generation. For a new CLI, pass --api-base-url to okibi generate.
Then check the credential on the machine that fails:
my-cli auth status my-cli doctor
Your Okibi API key is not a credential for your own API. The generated CLI needs a credential your API accepts, with the right permissions.
A plan limit blocks a build
When your workspace runs out of an allowance, the build doesn't start:
- In the CLI:
api 402: plan limit reached: your plan is out of successful_generations. Upgrade in the dashboard billing settings.The name afterout ofcan differ. - In the app:
Plan limit reached. Upgrade your plan to generate again.
Check your plan and balances with okibi billing status, or open Settings, then Plan. Feedback that repairs a finished build doesn't use another generation. See Plans and billing.
the platform is at its concurrent-generation capacity. Try again in a few minutes is not about your plan. Wait a few minutes and try again.
Report a problem
Email hello@okibi.ai with:
- The output of
okibi --version - The command you ran, with any keys removed
- Your workspace slug and the run ID
- The output of
okibi status <run-id> --json - What you expected to happen
Never send API keys (they start with okb_) or install commands printed by okibi clis install. Report security issues to the same address. See How Okibi handles your code.