# Agent and CI mode

> Run okibi without prompts, read its JSON, and handle its errors in scripts and agents.

Add `--agent` to any okibi command when a script or a coding agent runs it:

```sh
okibi --agent clis show my-cli
```

`--agent` turns on three things at once:

- **No prompts.** okibi never stops to ask a question. Steps that need a person in a browser, such as `okibi auth publisher`, return `approval_required` with the URL to open.
- **JSON output** wherever the command supports it.
- **Structured errors**, so a failure can be read as data instead of scraped from text.

Most listing and management commands also accept `--json` on its own, for JSON without the other two.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | The command succeeded |
| `1` | The command failed |

With `--agent`, a failure prints JSON to stdout:

```json
{"ok": false, "error": "…"}
```

Without `--agent`, the error is plain text on stderr.

`okibi generate --review` exits `0` when the run stops for spec approval. That pause is not a failure.

## Run okibi in CI

1. Create a workspace-locked key with `okibi keys create --name ci --workspace acme` and store it as the secret `OKIBI_API_KEY`. See [Log in](https://okibi.ai/docs/cli/login.md#keys-for-ci).
2. Install okibi in the job and run commands with `--agent`:

```sh
curl -fsSL https://okibi.ai/install | sh
export PATH="$HOME/.local/bin:$PATH"
okibi --agent generate --repo https://github.com/OWNER/REPO --name my-cli --no-pull
```

`--no-pull` skips downloading the finished CLI when the job only needs the hosted release. Set `OKIBI_NO_AUTO_UPDATE=1` to pin the installed version for the job.

## Retry safely

Messages to a running generation take a stable `--request-id`. Reuse the same id and the same text after an ambiguous failure, and okibi won't deliver it twice:

```sh
okibi --agent message <run-id> --text "Add pagination" --request-id fix-pagination-1 --wait
```

## Things that always need a human

- **Deleting a CLI.** `okibi clis delete` refuses to run with `--agent`. A person must type the CLI name in a terminal.
- **Logging in.** The first login opens a browser or prints a device code.
- **Paid plan changes.** `okibi billing change` needs `--yes`, which confirms the charge.