# Agent quickstart

> Instructions for a coding agent that has been asked to build a CLI with Okibi.

This page is written for coding agents. If you are a person, paste the prompt from [Set up with your agent](https://okibi.ai/docs/set-up-with-your-agent.md) into your agent instead.

You are going to turn the user's code or API into a CLI with Okibi. The build runs on Okibi's hosted platform. You only drive the `okibi` client.

## 1. Install okibi

Skip this if `okibi --version` already works.

**macOS and Linux**

```sh
curl -fsSL https://okibi.ai/install | sh
export PATH="$HOME/.local/bin:$PATH"
```

**Windows**

```powershell
irm https://okibi.ai/install.ps1 | iex
```

## 2. Check the login

```sh
okibi --agent auth status
okibi --agent workspaces
```

If there is no login, **stop** and ask the user to run `okibi auth login` in their own terminal. It opens a browser. Do not ask for, print, or save their API key.

If the user names a workspace other than their default, add `--workspace <slug>` to every command.

## 3. Agree on one source

Ask the user which source to build from, then repeat it back before you run anything:

| Source | Command |
| --- | --- |
| A local codebase | `okibi generate <dir> --name <cli-name>` |
| A GitHub repository | `okibi generate --repo https://github.com/OWNER/REPO --name <cli-name>` |
| Public API docs | `okibi generate --docs https://docs.example.com/api --name <cli-name>` |
| An OpenAPI document | `okibi generate --spec <path-or-https-url> --name <cli-name>` |

Rules:

- Use **exactly one** source flag.
- A local directory is uploaded for the hosted run. Only upload it after the user has said it is the source.
- CLI names are 1 to 64 lowercase letters, numbers, or hyphens. They start with a letter and end with a letter or number.
- Add `--api-base-url` only when the user gives you an API origin that the source does not already state.

## 4. Run it

```sh
okibi --agent generate --repo https://github.com/OWNER/REPO --name my-cli
```

The command streams progress and downloads the finished CLI into `./my-cli` when the run succeeds.

If the user wants to read the spec first, add `--review`. It works only for a local codebase or `--repo`, not for `--docs` or `--spec`. The command exits `0` when the run stops for approval. Then:

1. Show the user the proposed spec with `okibi spec show <cli-name> <run-id>`.
2. Run `okibi spec approve <run-id>` only when they agree.
3. Wait with `okibi --agent status <run-id>`, then download with `okibi --agent pull <run-id> --out ./my-cli`.

If the run is detached or the download was skipped, use the run id from the output:

```sh
okibi --agent status <run-id>
okibi --agent pull <run-id> --out ./my-cli
```

## 5. Report back

You are done when you can tell the user all four of these:

1. The run id.
2. The source you built from.
3. The CLI name.
4. The directory the CLI was downloaded to.

Report what the hosted run said. Do not claim checks or live API behavior that the okibi output did not show.

## Do not

- Do not look for or run local build tools such as `shipcheck`. The build runs on Okibi.
- Do not run `okibi clis delete`. It needs a human.
- Do not change the user's plan. `okibi billing change` charges them.