# Troubleshooting > Fix common problems with login, repositories, builds, installs, and generated CLIs. Find the symptom or message you see. okibi prints errors from the Okibi API as `api : `. ## 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: ```sh 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: ```sh 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](https://okibi.ai/docs/cli/login.md#keys-for-ci). 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: ```sh okibi auth login --device-code ``` okibi 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](https://okibi.ai/docs/cli/login.md#keys-for-ci). ## Repository missing Private repositories need the Okibi GitHub App on the account that owns them, with access to that repository. **In the app** 1. Click **Repos** in the sidebar, then click **Sync**. 2. 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**. 3. Go back to **Repos** and click **Sync** again. **In the CLI** ```sh okibi repos okibi auth github status okibi auth github manage OWNER ``` `okibi repos` refreshes the list from GitHub. `okibi auth github status` shows each connected account and its repository access. `okibi auth github manage` opens that account's GitHub App settings, where you can add the repository. 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. **In the app** Open the project and click **Builds**. Click **Approve & build** to build, or **Request changes** to tell the agent what to change. **In the CLI** ```sh okibi spec show my-cli okibi spec approve okibi spec reject --feedback "Rename list to ls" ``` `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](https://okibi.ai/docs/guides/approve-the-spec.md). ## Build failed `okibi generate` ends with `run failed` and the reason, then prints the last lines of output. To look again later: ```sh okibi status okibi status --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: ```sh okibi message status okibi status ``` - 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 ` again to get the corrected CLI. - If the repair fails or is cancelled, the previous result stays available, and `okibi status` says 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](https://okibi.ai/docs/guides/runs-and-chat.md). ## 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: ```sh 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 `. | | `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](https://okibi.ai/docs/guides/releases.md). ## 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: ```sh 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: ```sh 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 after `out of` can 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](https://okibi.ai/docs/guides/billing.md). `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](mailto: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 --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](/security).