skills/kora-cli/SKILL.md

---
name: kora-cli
description: "Read when installing the Kora CLI (@kora-platform/cli), connecting a terminal or coding agent to Kora SaaS or a self-managed deployment, signing up or logging in, selecting an organization, using organization API keys for direct Platform HTTP API calls, or running kora commands non-interactively."
---

# Kora CLI

`kora` is the command-line client for Kora SaaS and reachable self-managed Kora
deployments. Use this skill when the user wants to manage Kora resources from a
terminal or needs direct Platform HTTP API access with organization API keys.
Installing or operating the deployment itself is the `kora-self-host` skill,
not this one.

Establish the target before giving setup instructions:

- **Kora SaaS** — use the CLI default, `https://kora-eu.raw-labs.com`; do not
  ask the user for a URL. SaaS onboarding provisions the user's organization
  and production environment. Do not run the self-managed installer, use
  `koractl`, or create another organization as part of first-time setup.
- **Self-managed Kora** — the user or operator supplies the deployment URL. If
  the deployment does not exist yet, route installation to `kora-self-host`.
- **Unknown** — use Kora SaaS by default. Ask for a URL only when the user says
  they operate or need to connect to a self-managed deployment.

## Install

```sh
npm install -g @kora-platform/cli
kora --help
```

Requires Node.js >=24.0.0.

## Point The CLI At Kora

Login base URL resolution order, first match wins:

1. `--base-url` flag on `kora auth login` / `kora auth signup`
2. `KORA_BASE_URL` environment variable
3. nearest `.kora/cli.toml` walking up from the working directory
4. `~/.config/kora/config.toml` (respects `XDG_CONFIG_HOME`)
5. Kora SaaS at `https://kora-eu.raw-labs.com`

After login the base URL is stored in the session, so subsequent commands
need no flag. The SaaS default is not written as a config override. Self-managed
local-mode installs serve `http://localhost:3000`. `kora auth signup` remains a
local-account command for self-managed deployments and prompts for a deployment
URL when no override is configured.

## Authentication

`kora auth login` has two flows:

- **Device approval (the SaaS and agent path).** `kora auth login` automatically
  uses browser device approval for the Kora SaaS default, OIDC-only deployments,
  and non-interactive shells such as coding-agent shell tools. `--device` forces
  it for any other configured deployment. The command prints a verification URL
  and confirmation code, then waits:

  ```sh
  kora auth login --base-url http://localhost:3000 --device
  ```

  The user opens `<base-url>/device?code=XXXX-XXXX`, signs in in the browser if
  needed, confirms the code matches the terminal, and approves. In OIDC-only
  deployments, the web login route continues directly to the configured
  identity-provider flow. The CLI then stores the session and the command
  completes on its own. Codes expire after 15 minutes; a denied or expired
  approval fails the command with a clear error. This flow also works on
  OIDC/SSO-only deployments, because authentication happens in the browser.

- **Interactive email/password.** For explicitly configured local or hybrid
  self-managed deployments, plain `kora auth login` prompts for credentials.

When driving Kora SaaS as a coding agent, run `kora auth login`, surface the
printed URL and confirmation code to the user, and wait for the command to
finish. Pass `--base-url` or set `KORA_BASE_URL` only for self-managed Kora.
Confirm with `kora auth whoami`; the session is stored on disk and every later
`kora` command picks it up automatically.

Notes:

- A SaaS user who needs a new account can open
  `https://kora-eu.raw-labs.com/signup` in the same browser. A self-managed user
  can open `<base-url>/signup`. Complete signup, then reopen the device
  verification URL before its code expires. OIDC-only login goes directly to
  provider sign-in and does not promise a Kora-page signup link.
  `kora auth signup` (TTY-only, local email/password accounts) remains
  available for interactive use.
- On a local-mode self-managed install, the first signed-up user becomes
  platform admin. Server installs require SSO sign-in with one of the configured
  verified platform-admin bootstrap emails; unverified local-auth first-user
  bootstrap is limited to local single-machine evaluation.
- Kora SaaS users sign in through its browser/OIDC flow. Opening the SaaS
  `/signup` entry creates or resumes the hosted onboarding flow; the terminal
  does not create the account or initial organization.
- Fully headless CI with no human in the loop: inject a session via
  `KORA_SESSION_JSON_B64` — see `references/auth-and-sessions.md`.

## First SaaS Session, End To End

```sh
npm install -g @kora-platform/cli
kora auth login
kora auth whoami
kora status
```

The device command prints a browser URL and approval code. After approval,
`whoami` must show the organization provisioned by SaaS onboarding. Do not run
`kora org create` as part of SaaS setup; hosted users use the organization
created by onboarding and cannot create additional organizations.

## First Self-Managed Session, End To End

```sh
npm install -g @kora-platform/cli
kora auth login --base-url http://localhost:3000 --device
kora auth whoami
kora org list --json
kora status
```

Create an organization only when the authenticated self-managed deployment has
none for this user and the user explicitly wants one. `kora org create` sets a
new organization active. With access to multiple organizations, switch with
`kora org select <org>` and check with `kora org current` or
`kora auth whoami`.

## Working Conventions

- Append `--json` for machine-readable output. Discover the surface with
  `kora help --json` and `kora help <command-path> --json` instead of
  guessing flags.
- Most commands require an active organization.
- Destructive commands (`kora org delete`, `kora org reset`, and similar)
  prompt for confirmation unless `--yes` is passed.
- Organization API keys (`kora access api-keys create`) authenticate direct
  Platform API HTTP calls; they are not a CLI login method in this release.

## Which Reference To Read Next

- `references/auth-and-sessions.md` — session storage and permissions,
  non-interactive session injection, base-URL precedence detail, OIDC
  behavior, and API keys
- `references/http-api.md` — live OpenAPI discovery, API-key bearer auth,
  roles for common integration calls, and workflow start/run polling examples
- `references/command-map.md` — top-level command families and aliases