# KiCI CLI: driving a deployed orchestrator

This bundle covers: Auth, org and orchestrator selection, runs, approvals, notifications, diagnostics, and the MCP server a coding agent connects to.

## Drive KiCI from your coding agent

Source: https://docs.kici.dev/user/ai-agents/

KiCI ships a hosted **MCP server** so a coding agent (Claude Code, or any MCP
client) can drive your CI directly: trigger runs, read a structured result,
fetch the failing step's logs, cancel, and re-run — all under an agent identity
you control, org-scoped, and audited. There are no per-tool tokens to configure:
point the agent at one URL with one credential and it's done.

The MCP exposes only what you can already do yourself through the `kici` CLI and
the dashboard. It is not a new privileged surface — every tool maps to an
existing user-facing operation and is gated by the same permissions your role
grants.

## 1. Mint an agent credential

The MCP accepts an **agent-kind credential** — and only an agent-kind one. It
can be either of two kinds:

- An **agent personal access token (PAT)** that you own — it acts as you, with
  your provenance. The token is `kici_pat_…`.
- An **agent org API key** that belongs to your organization — a
  provenance-carrying service account, independent of any one person. The key is
  `kici_sk_…`.

Both drive the MCP identically. A non-agent token of either kind (a plain user
PAT, a plain org API key) is refused at the door.

**Option A — an agent PAT.** Mint one with the `kici` CLI (log in first with
`kici login`):

```bash
kici pat create --agent --name "claude-code"
```

The `--name` value is the **agent label**. It is recorded on every action the
agent takes, so your audit log shows exactly which agent did what (and on whose
behalf). The token is printed once — save it now; it cannot be retrieved later.

**Option B — an agent org API key.** Create one from the dashboard's
**Settings → API keys** tab: set the key's kind to **Agent** and give it an
agent name (the agent label). The same key can also be minted with
`kici-platform-admin user api-key create --org <id> --agent --agent-label <label>`.
Reach for an org agent key when the agent should act as a shared service account
rather than as a single user — for example, a long-lived CI bot that outlives any
individual's membership.

Whichever you pick, the credential carries provenance, not extra authority. Its
effective permissions are the matrix it was minted with, and that matrix can
never exceed the permissions of the person who created it — so you can scope an
agent credential **below** your own access (for example, read-only) and the agent
is held to that smaller set. Powerful operator capabilities (secret rotation,
agent and peer management, draining) are intentionally **not** exposed here. See
[the agent safety model](https://docs.kici.dev/user/ai-agents/#6-the-agent-safety-model) for how scoping and
confinement work.

## 2. Point your coding agent at the MCP server

KiCI's hosted MCP server lives at one fixed URL:

```
https://api.kici.dev/api/v1/mcp
```

Configure your MCP client with that URL and your agent credential (the agent PAT
or the agent org key) as a Bearer credential. For Claude Code:

```bash
claude mcp add --transport http kici https://api.kici.dev/api/v1/mcp \
  --header "Authorization: Bearer <your-agent-credential>"
```

That's the entire setup. The agent can now call the tools below.

## 3. What the agent can do

**Read**

- `list_runs` — recent runs in your organization.
- `get_run` — the structured, provenance-tagged result of a run: the typed job
  graph, per-step statuses and exit codes, durations, and a derived failure
  category.
- `get_step_logs` — the log lines for a specific step.
- `list_workflows` — your registered workflows, optionally filtered by
  `triggerType`, `repo`, or `stale` (only those not triggered within a duration
  like `30d`).
- `list_orgs` — the organizations you belong to. Use it to discover the `orgId`
  to pass to the other tools when you're a member of more than one.
- `list_secrets` — the secret scopes in your organization and the **key names**
  each holds. Secret values are never returned — only the names.
- `list_orchestrators` — the connected orchestrator clusters your runs execute
  on (cluster name, routing keys, version, scaler backends, health).
- `get_diagnostics` — your organization's execution metrics over the last 24
  hours (run count, success rate, average duration, queued and running jobs)
  plus per-orchestrator connection health.

**Drive**

- `trigger_run` — run a registered workflow ("run now").
- `rerun_run` — re-run a completed run.
- `cancel_run` — cancel an in-progress run.
- `approve_run` — approve a held approval gate for a run (name the run, plus
  `job`/`step` to disambiguate when it has multiple holds). Requires
  `runs:write` **and** the permission matching the hold's type — `ci_trust:write`
  for a security hold, `contexts:admin` for a wait-timer hold, `contexts:write`
  otherwise. That is the same rule the dashboard and the `kici` CLI answer to,
  so an agent cannot release a hold a person with the same grants could not.
  Grant agent credentials accordingly.
- `reject_run` — reject a held approval gate; a `reason` is required. Gated
  identically to `approve_run`.
- `cancel_runs_by_branch` — cancel all in-progress runs on a branch (bounded —
  up to 100 per call; a `truncated` flag tells the agent to re-invoke).

The tools cover the same developer operations you can drive yourself with the
`kici` CLI. Operations that are purely local to your machine (scaffolding,
compiling, running a workflow locally) or that mint credentials are
intentionally not exposed — the agent works against your deployed CI, not your
filesystem.

If you belong to a single organization, the org is resolved automatically. If
you belong to several, pass an `orgId` argument to any tool (use `list_orgs` to
find it).

Only an **active** membership counts: an organization you have been suspended
in, one that has been disabled, and one that has been deleted are all skipped.
So a single active membership alongside a disabled one still resolves
automatically, and a tool call against an organization you are suspended in is
refused with the same message the dashboard gives.

### Limits and pagination

The MCP server applies a few bounds so an agent loop can't overwhelm the shared
infrastructure. They are agent-visible — your agent gets a clear tool error and
should back off or page, never a silent truncation:

- **Per-token request limits.** Each agent token has its own ceiling, refreshed
  every minute: **120 reads/minute** (listing and fetching runs, step logs, and
  workflows) and **20 run actions/minute** (cancel, re-run, trigger, approve,
  reject, cancel-by-branch). The two
  budgets are independent. An over-limit call returns a tool error telling the
  agent which kind of operation was throttled and how many seconds to wait
  before retrying.
- **Paginated step logs.** `get_step_logs` returns log lines in pages. Pass a
  `limit` to bound a page (capped server-side) and follow the returned
  `nextCursor` (as `cursor` on the next call) to read more. A large step log is
  paged, never silently cut off — when `nextCursor` is null you've reached the
  end.
- **Bounded run results.** `get_run` returns the structured run result, which is
  naturally bounded by workflow size. For a pathologically large run it returns a
  tool error directing the agent to inspect specific steps with `get_step_logs`
  instead.

## 4. Why the structured result is agent-safe

Every tool returns a machine-first shape designed for an agent to reason over
without being misled by repository content. Each field that comes from your repo,
a contributor, or a process's output — workflow and job names, refs, error
messages, log lines, job outputs — is delivered **fenced** as untrusted data:
wrapped in a per-response, randomly-named delimiter (`⟦u:<nonce>⟧…⟦/u:<nonce>⟧`),
with the result prefixed by a notice that fenced text is data, never instructions.
KiCI-generated values (ids, statuses, exit codes, durations, the derived failure
category) are left plain. So an agent can keep user-controlled content out of its
instruction channel by treating anything inside a fence as data only. See
[Untrusted content and prompt injection](https://docs.kici.dev/user/ai-agents/#7-untrusted-content-and-prompt-injection)
for the full model.

Secret values are never returned — only the names of the secret keys a step
accessed.

## 5. The audit guarantee

Because the MCP accepts only an agent-kind credential, **every action that flows
through it is agent-attributed by construction** — there is no path that produces
an untagged, human-looking action. Each read and each drive operation is recorded
in your orchestrator's access log under the acting identity plus the agent label,
so you always have a complete trail of what your agent did.

Inspect that trail with `kici-admin access-log list --json` (or
`kici-admin access-log show <id>` for one entry). The acting identity depends on
which credential you used:

- An **agent PAT** keeps `actor_type` as `user` and `actor_id` as your own
  identity — the agent provenance rides in the actor metadata as `agentLabel`
  (the `--name` you minted the PAT with) and `agentPatId`.
- An **agent org key** keeps `actor_type` as `api_key` and `actor_id` as the key
  — the same `agentLabel` provenance rides in its actor metadata.

Either way the label is stored in a dedicated `agent_label` column on every such
row, so you can filter the access log down to just agent activity:

```bash
# Every action a specific agent took, by its label:
kici-admin access-log list --agent-label "claude-code"

# Every agent-attributed action, across all agents:
kici-admin access-log list --agent-only
```

In the dashboard, agent-driven activity is visually distinguished: the
[Activity](https://docs.kici.dev/user/dashboard/activity-and-dlq/#activity) log renders an **agent badge**
on every agent-attributed row, and a run's **Triggered by** shows the same badge
when an agent triggered or cancelled it — so an agent's footprint is obvious at a
glance, not buried in metadata.

## 6. The agent safety model

KiCI treats a coding agent as a **least-privilege principal with its own token**,
not as an unscoped extension of you. Three properties make the agent
"confined and audited by construction":

**Least-privilege, capped at the creator.** An agent token is scoped when you
mint it. Leave the scope open and it inherits your role; narrow it and the agent
is held to that smaller set — its effective permissions are always the
**minimum** of your role and the token's scope. A token can never grant more than
you hold, so an agent cannot escalate beyond its creator.

**Repository scope comes along too.** If your role is restricted to a set of
repositories, an agent token you mint is restricted to the same set. Runs
outside it are not there: they are filtered out of `list_runs`,
`cancel_runs_by_branch` skips them, and naming one directly answers "not found"
— the same answer a run id that does not exist gets, so an agent cannot use the
tools to discover which repositories it is missing. Your organization's audit
log records the real reason. One thing to know when you choose which credential
to give an agent: this inheritance applies to a **personal** agent token. An
**organization** agent API key has no minting user's role to inherit from, so it
reaches every repository in the organization within its permission level — reach
for a personal agent token when repository scoping is what you want.

**Fail-closed denial, on every surface the token is used.** The scope is enforced
wherever the token acts — the MCP tools the agent drives **and** any direct API
call made with the raw token. When the agent attempts something outside its
scope (driving a run with a read-only token, reading members it wasn't granted),
the action is **refused fail-closed**: it does not run, nothing is changed, and a
clear "insufficient permission" error comes back. There is no fallback path that
quietly lets a denied action through.

**Every decision is audited — allowed and denied alike.** Allowed actions are
recorded in your access log under your identity plus the agent label, exactly as
described in [the audit guarantee](https://docs.kici.dev/user/ai-agents/#5-the-audit-guarantee). **Denials are audited
too:** each refused action lands a row in your organization's audit log carrying
the agent label and the permission that was required, so a confined agent's
attempts are as visible as its successes. You can see both what your agent did
and what it was stopped from doing.

**Execution stays confined.** Beyond authorization, the workloads an agent
triggers run under the same execution guardrails as any other run — label-based
routing decides where a job runs, and privileged (root) execution is gated and
verified, refused fail-closed when the guarantee can't be met.

Together these mean you can hand an agent a deliberately narrow token, point it
at KiCI, and trust that it can do exactly what you granted — no more — with a
complete, tamper-evident trail of every allow and every deny.

## 7. Untrusted content and prompt injection

A run carries content KiCI does not vouch for — log lines, workflow and repository
names, error text, contributor names. An agent reading a run must treat that content
as **data**, never as instructions, or a crafted log line ("ignore previous
instructions and …") could hijack the agent.

KiCI defends this structurally:

- **Provenance tagging.** Every user- or process-controlled value is marked untrusted
  at the API boundary; KiCI's own values (run ids, statuses, exit codes, commit hashes)
  are trusted.
- **Fencing at the agent boundary.** When the MCP server returns a result, every
  untrusted value is wrapped in a per-response, randomly-named fence
  (`⟦u:<nonce>⟧…⟦/u:<nonce>⟧`) and the result is prefixed with a notice that fenced
  text is data, never instructions. The fence name is random per response, so injected
  content cannot forge a closing fence to break out.
- **No mutation.** KiCI never rewrites your log content — it fences and labels it. The
  agent sees the true bytes inside the fence.

### Safe integration pattern

An agent (or harness) consuming KiCI reads should treat anything inside a fence as
opaque data: quote it, summarize it, search it — but never execute it, follow it, or
let it redirect a tool call. Any action taken off the back of a read (re-run, cancel,
trigger) should be a deliberate decision from the trusted skeleton (statuses, exit
codes, the failure category), not from fenced content.

### Sandboxing actions

Actions an agent drives through KiCI run under the agent's own least-privilege identity
and are audited; combine the fencing contract with that confinement so that even if a
log line tries to provoke an action, the action is bounded by the agent token's scope.

---

## CLI authentication

Source: https://docs.kici.dev/user/cli-auth/

The KiCI CLI supports three authentication methods: browser-based OAuth (default), device authorization flow (for headless environments), and API key paste (for CI/CD pipelines).

## Authentication methods

### Browser OAuth (default)

The default `kici login` flow:

1. Opens your default browser to the KiCI identity provider
2. You authenticate in the browser
3. The CLI receives a token via localhost callback
4. A personal access token (PAT) is created and stored locally

```bash
kici login
```

The CLI auto-detects headless environments (SSH sessions, CI runners, containers) and switches to device flow automatically. On WSL, `kici login` opens your Windows browser when Windows interop is reachable; if it is not (interop disabled, or the Windows drive not mounted), the CLI falls back to the device flow rather than waiting for a browser that cannot open.

### Device flow (headless)

For environments without a browser (SSH, remote servers):

```bash
kici login --device
```

This displays a URL and a code. Open the URL on any device, enter the code, and authenticate. The CLI polls for completion.

### API key paste

For CI/CD pipelines and automated environments, paste an API key directly:

```bash
kici login --token kici_sk_abc123...
```

The API key (starts with `kici_sk_`) is passed directly as the flag value and stored in your local config file.

## kici logout

Revoke your PAT and clear local authentication:

```bash
kici logout
```

This:

1. Revokes the PAT on the server (preventing further use)
2. Detaches the local dev plane if it is attached, so a logged-out user is not left with a hybrid plane holding an orphaned orchestrator key
3. Clears the auth fields from the local config file — the PAT, its id and expiry, your email, and the active organization
4. Preserves the connection settings (per-org default clusters, Platform endpoint, orchestrator endpoint, OIDC issuer, routing key)

Server revocation is best-effort: if the network call fails, the local config is still cleared.

## Organization management

### List organizations

```bash
kici org list
```

Shows all organizations you belong to, with your role in each. The active organization is marked with an asterisk.

### Switch active organization

```bash
kici org use <name-or-id>
```

Name matching is case-insensitive. You can also use the organization ID directly.

The active organization is both the scope for org-scoped commands (`kici runs list`, `kici diagnostics`, `kici secrets list`, …) **and** the default target for `kici run remote`. After `kici login` and `kici org use <org>`, `kici run remote` dispatches to that org through the Platform — that is the complete path to a remote run. Override the target for a single run with `kici run remote --org <id>`.

If an organization has more than one connected orchestrator cluster, set its default cluster once with `kici orchestrators use <name>` (list them with `kici orchestrators list`). `kici run remote` then targets that cluster unless you pass `--orchestrator <name>`. With a single connected orchestrator the cluster is selected automatically.

### Show current organization

```bash
kici org current
```

Displays the currently active organization name and ID.

## Auth status

`kici org current` shows your current login state and active organization:

```bash
kici org current
```

It reports whether you are logged in and which organization is active. PAT
expiry and the full list of your tokens are managed from the dashboard (see
"Dashboard management" below).

## Personal access tokens

Personal access tokens (PATs) are created automatically when you log in via OAuth. You can also create and manage PATs through the dashboard.

### How PATs work

- **User-scoped**: PATs work across all organizations you belong to
- **120-day default expiry**: Configurable when creating from the dashboard
- **Named per machine**: Each login creates a PAT named after the machine hostname
- **Permission inheritance**: PATs inherit your effective role permissions in each org

### PATs vs API keys

|            | Personal access tokens | API keys        |
| ---------- | ---------------------- | --------------- |
| Scope      | User (cross-org)       | Organization    |
| Prefix     | `kici_pat_`            | `kici_sk_`      |
| Created by | CLI login or dashboard | Dashboard       |
| Expiry     | 120 days (default)     | No expiry       |
| Use case   | Developer CLI access   | CI/CD pipelines |

### Dashboard management

Create, view, and revoke PATs from the dashboard:

1. Click your avatar in the sidebar
2. Select **Account settings**
3. Navigate to the **Personal access tokens** tab

From here you can:

- Create PATs with custom names and expiry periods
- View active PATs with their prefixes and expiry dates
- Revoke PATs that are no longer needed

## Reaching the Platform API directly

The Platform exposes a versioned REST API under `/api/v1/*`. The same endpoints back the dashboard SPA, the `kici` CLI, and any third-party automation. There is no separate "public" surface — the dashboard's API is the API.

### Base URL

| Deployment  | Base URL pattern                                                          |
| ----------- | ------------------------------------------------------------------------- |
| KiCI Cloud  | `https://<your-platform-host>/api/v1/`                                    |
| Self-hosted | `https://<orchestrator-host>/<deployment-slug>/api/v1/` (slug is optional |
|             | — `KICI_BASE_PATH` may add a prefix when the Platform is reverse-proxied) |

`/api/v1/*` requires authentication (see below). `/health`, `/metrics`, and `/ws` (WebSocket) sit outside that prefix and have their own access posture (`/metrics` is meant for Prometheus scrape, not public exposure).

### Authentication

Every request to `/api/v1/*` carries an `Authorization: Bearer <token>` header. The Platform routes on the prefix:

| Prefix      | Token type                    | Created via                             | Scope            |
| ----------- | ----------------------------- | --------------------------------------- | ---------------- |
| `kici_pat_` | Personal access token         | `kici login` or dashboard               | User (cross-org) |
| `kici_sk_`  | User API key                  | Dashboard → Settings → API keys         | Org              |
| `kici_sa_`  | Service account key           | Dashboard → Settings → Service accounts | Org              |
| (other)     | OIDC JWT or opaque OIDC token | OIDC login (browser SPA)                | User (cross-org) |

JWT and opaque OIDC tokens are validated against the configured OIDC issuer (JWKS for JWTs, the issuer's UserInfo endpoint for opaque ones). All `kici_*` tokens are validated by SHA-256 hash lookup against the Platform DB. See [RBAC: authentication methods](https://docs.kici.dev/architecture/security/rbac/#authentication-methods) for the full model.

> **Note:** `kici_ok_` keys are **not** for the HTTP API — they authenticate orchestrator-to-Platform WebSocket connections only. Use `kici_sk_` (or `kici_pat_`) for HTTP calls.

### Permissions

Tokens authenticate; RBAC authorizes. Every org-scoped route runs `orgContextMiddleware` (verifies you are a member of the target org) followed by `requirePermission(resource, level)`. The 18 resources and 5 levels are documented in [RBAC](https://docs.kici.dev/architecture/security/rbac/#permission-model). User API keys carry their own permission matrix bounded above by the creator's effective permissions; PATs inherit the user's role permissions (or are capped further by their `scopes` field).

### Configurable surfaces

The dashboard is a browser SPA on top of the same `/api/v1/*` surface, so nearly everything you can configure in the dashboard you can configure over HTTP. The exception is a short list of routes that only a **browser session** may call, marked † below. The mounted route groups include:

- **Auth & identity:** `/cli/exchange-token`†, `/pats`, `/user`, `/identity-links`, `/identity-links/:id` (DELETE)†, `/github-oauth`, `/auth/github/link`†, `/invites`, `/invites/pending`, `/invites/:inviteId/{accept,decline}`†
- **Org & membership:** `/orgs` (POST)†, `/orgs/:customerId`, `/orgs/:customerId/{members,roles,api-keys,orchestrator-keys,service-accounts,billing,trust-policies}`
- **Workflows & runs:** `/orgs/:customerId/{runs,registrations,workflows,held-runs,contexts,secrets,global-workflows}`
- **Webhooks & event log:** `/orgs/:customerId/{sources,webhook-endpoints,event-log}`
- **Diagnostics & activity:** `/orgs/:customerId/{diagnostics,activity,access-log}`

**† Browser session only.** These routes answer **403** with `This endpoint requires an interactive login` to a `kici_pat_`, `kici_sk_` or `kici_sa_` token. They are the routes that create an organization, join or decline one, unlink a provider identity, start a GitHub account link, and exchange your session for a personal access token. Each mints a credential wider than the credential presenting it, or changes which organizations and provider identities your account reaches. A `kici_sk_` or `kici_sa_` token is bound to one organization and one permission set, so letting it take those actions would hand it access it was never granted. Do them in the dashboard, or with `kici login`, which runs the browser flow for you.

`POST /pats` is the one route in between: it accepts a browser session **or** an existing `kici_pat_` (so `kici pat create` keeps working), and refuses `kici_sk_` and `kici_sa_`. A token minted from another token can never be wider than that token. The new token is capped by your own permissions **and** by the scopes of the token you called with, whether or not you pass `permissions` explicitly. Mint from an unscoped session when you need a broader token.

The full route tree is the source of truth — every method, request schema, and response schema is enumerated server-side. There is currently no auto-generated OpenAPI spec; the typed `DashboardApiType` export is the canonical contract for TypeScript clients.

### Calling the API

Two short examples — adapt the base URL and token to your deployment.

**curl (PAT or API key):**

```bash
TOKEN="$(grep -E '^pat=' ~/.kici/config | cut -d= -f2)"   # or paste a kici_sk_…
ORG="<your-org-id>"
curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  "https://<orchestrator-host>/<deployment-slug>/api/v1/orgs/$ORG/runs?limit=5" | jq
```

**Browser console (after dashboard login):**

Mint a personal access token and pass it explicitly. Do not script against the
dashboard's own session token. That token is short-lived and tied to your
identity-provider session, so anything built on it stops working at the next
renewal or sign-out.

```js
// kici pat create --name console --expires-in-days 1   → prints the token
const token = 'kici_pat_...';
const res = await fetch('/<deployment-slug>/api/v1/orgs/<your-org-id>/runs?limit=5', {
  headers: { Authorization: `Bearer ${token}` },
});
console.log(await res.json());
```

### Rate limits and body size

There is currently no per-token rate limit on `/api/v1/*`. A single global body-size cap applies to webhook ingress and dashboard API requests alike.

### Audit trail

Every `/api/v1/*` mutation that touches tenant-plane data is recorded in the upstream tenant-plane audit log, stamped with the actor (user, API key, service account, or upstream operator on a break-glass support read). Reads on customer data go through the orchestrator over the WebSocket proxy and land in the orchestrator's `access_log` table. See [Audit log](https://docs.kici.dev/operator/security/audit-log/) for the orchestrator schema and the dashboard's "Activity" page for the federated view.

## Token storage

The CLI stores authentication data in `~/.kici/config` with `0600` permissions (owner read/write only). The config file contains:

- PAT token, its server-side id, and its expiry date
- The email address from your OIDC token
- Active organization ID
- Per-org default orchestrator clusters
- Platform endpoint URL, orchestrator endpoint URL, and the OIDC issuer the PAT was minted against
- Routing key for webhook source identification
- API key, when you logged in with `--token`

The web dashboard holds none of these. It keeps only the tokens of your current
sign-in, in browser storage for the tab's origin. It does not request offline
access, so those tokens die with your identity-provider session instead of
staying valid for weeks. Its origin also serves a Content-Security-Policy that
restricts which scripts run and which hosts the page may contact.

## Troubleshooting

### Browser doesn't open

If `kici login` can't open a browser:

- Copy the authorization URL the CLI prints under `If it does not open, visit:` and open it in any browser — the CLI keeps waiting for the callback for up to 5 minutes (see [Browser callback never arrives](https://docs.kici.dev/user/cli-auth/#browser-callback-never-arrives) if it never lands)
- Use `kici login --device` for the device flow
- Or set the `KICI_BROWSER_CMD` environment variable to your browser command (e.g., `KICI_BROWSER_CMD='firefox {url}'`)

### Browser callback never arrives

If the browser opens and you complete sign-in, but `kici login` keeps waiting:

- The CLI is waiting on a callback to `127.0.0.1`. A corporate firewall, an unusual loopback policy, or a WSL `portproxy` rule can block it.
- After 90 seconds of waiting the CLI prints a reminder that `kici login --device` needs no callback. It is safe to ignore if you are still signing in. After 5 minutes it gives up with `Authentication timed out after 5 minutes`.
- Retry with `kici login --device` — the device flow needs no local callback.
- If you must keep the browser flow, set `KICI_CALLBACK_PORT` to a fixed port your firewall allows.

### Callback port already in use

If `KICI_CALLBACK_PORT` names a port something else is already listening on, `kici login` stops immediately and names the port instead of hanging or crashing.

It deliberately does **not** pick another port for you. A fixed port is something you set on purpose — usually because a firewall rule or a WSL `portproxy` entry allows exactly that one — so binding somewhere else would hand the browser a callback URL nothing can reach, and you would wait out the full 5-minute timeout instead of seeing a clear error.

Two ways forward:

- Free the port (stop whatever holds it) or point `KICI_CALLBACK_PORT` at a different free port your firewall allows.
- Run `kici login --device` — the device flow needs no local callback at all.

A port below 1024 fails the same way, with a permissions message rather than an "in use" one: those ports need elevated privileges. Pick a port above 1024. A value that is not a port number at all — non-numeric, negative, or above 65535 — is rejected before the login starts, naming the value you set.

### Device code expired

This is the device flow's own expiry, not the browser flow's callback timeout above.

The device code is issued by the identity provider, which also sets how long it lives. The CLI prints the lifetime with the code (`Code expires in N minutes`) and polls until you approve or the code expires. On expiry it stops with `Device code expired`. If that happens:

- Run `kici login --device` again to get a new code
- Ensure you're using the correct URL displayed by the CLI

### Expired PAT

If you see "Personal access token has expired":

- Run `kici login` to create a new PAT
- The old expired PAT is automatically superseded

### "Not a member" errors

If authenticated commands return 403:

- Check your active org: `kici org current`
- List available orgs: `kici org list`
- Switch to the correct org: `kici org use <name>`

### Connection refused

If the CLI can't reach the server:

- Verify the endpoint: check `~/.kici/config` for the correct URL
- Test connectivity: `curl <your-platform-url>/health`

---

## kici: account & org

Source: https://docs.kici.dev/user/cli/account-and-org/

## Guide

### kici login

Authenticate with KiCI via browser-based OAuth (default) or API key (`--token`).

By default, `kici login` opens your browser for OIDC authentication using PKCE. In headless environments (SSH, CI, containers), it automatically switches to the RFC 8628 device authorization flow where you visit a URL and enter a code.

The browser flow completes by receiving a callback on `127.0.0.1`. If that callback is blocked, pass `--device` to use the device flow instead — it needs no local callback. See [CLI authentication](https://docs.kici.dev/user/cli-auth/#browser-callback-never-arrives) for the full troubleshooting steps.

After OAuth, the CLI exchanges the OIDC token for a personal access token (PAT) stored in the config directory (`~/.kici/config` by default, overridable with `KICI_CONFIG_DIR`).

`kici login` targets the hosted KiCI Platform by default. To authenticate against another KiCI environment (staging, or a testing OIDC provider, for example), pass `--platform-endpoint` / `--oidc-issuer` or set `KICI_PLATFORM_URL` / `KICI_OIDC_ISSUER`. Login persists the platform endpoint and OIDC issuer it authenticated against alongside the PAT, so a saved PAT always matches its endpoint. Because the config describes one environment at a time, **switching the endpoint resets the active organization and default clusters** — re-run `kici org use <name>` after switching environments.

```bash
kici login [options]
```

**Environment variables:**

| Variable              | Default                                      | Description                                                            |
| --------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
| `KICI_PLATFORM_URL`   | `https://api.kici.dev`                       | Platform API base URL (override to target another KiCI environment)    |
| `KICI_OIDC_ISSUER`    | `https://auth.kici.dev/realms/kici-internal` | OIDC issuer URL (override to target another KiCI environment)          |
| `KICI_OIDC_CLIENT_ID` | `kici-cli`                                   | OIDC client ID (override to target another KiCI environment)           |
| `KICI_BROWSER_CMD`    | uses `open` package                          | Custom browser command with `{url}` placeholder, or `none` to suppress |
| `KICI_CALLBACK_PORT`  | random                                       | Fixed port for OAuth PKCE callback server                              |
| `KICI_CONFIG_DIR`     | `~/.kici`                                    | Override config directory                                              |

**Examples:**

```bash
# Browser-based OAuth login (default)
kici login

# Force device flow (for SSH/headless)
kici login --device

# Legacy API key login
kici login --token kici_sk_abc123...

# Log in against another KiCI environment (e.g. a testing instance)
kici login --platform-endpoint https://platform.example.com \
  --oidc-issuer https://auth.example.com/realms/kici-internal

# Suppress browser opening (print authorize URL to stdout)
KICI_BROWSER_CMD=none kici login

# Use custom browser command
KICI_BROWSER_CMD='firefox {url}' kici login

# Fixed callback port and custom config directory
KICI_CALLBACK_PORT=19876 KICI_CONFIG_DIR=/tmp/kici-test kici login
```

**Headless detection:** The CLI checks, in order:

1. SSH session — `SSH_CONNECTION`, `SSH_CLIENT`, or `SSH_TTY` set.
2. CI — `CI`, `GITHUB_ACTIONS`, or `GITLAB_CI` set to anything other than the explicit opt-outs `0` and `false` (any case), so exporting `CI=0` on a desktop keeps the browser flow. An opt-out cancels that one marker only — `CI=false GITHUB_ACTIONS=true` still selects the device flow, and `GITHUB_ACTIONS=false` opts that marker out without affecting `CI`. See [Environment variables](https://docs.kici.dev/user/env-vars/#how-ci-is-interpreted) for the full convention.
3. Container — `container` or `DOCKER_CONTAINER` set, or the `/run/.containerenv` / `/.dockerenv` sentinel files present.
4. WSL — an interactive desktop, so **not** headless, but only when Windows interop is reachable: the browser flow opens your Windows browser and the localhost callback is normally reachable through WSL's localhost forwarding (a `portproxy` rule or firewall policy can still block it — pass `--device` if it does). When interop is unreachable (it is disabled, or the Windows drive is not mounted) no Windows browser can be launched, so WSL counts as headless and the device flow is used. The same applies when the interop check does not answer within a couple of seconds — the signature of a hung Windows drive mount — so a wedged mount falls back to the device flow instead of stalling the login.
5. Linux without a display server — neither `DISPLAY` nor `WAYLAND_DISPLAY` set.

The first match wins, so an SSH session into WSL, or a container running on a WSL host, stays on the device flow.

### kici logout

Revoke your personal access token on the server and clear local credentials.

If the server is unreachable, local credentials are still cleared (the PAT will expire automatically). Non-auth config fields (active org, default clusters, etc.) are preserved.

```bash
kici logout
```

**Examples:**

```bash
# Log out and revoke PAT
kici logout
```

### kici init

Initialize a `.kici/` directory with default workflow templates.

```bash
kici init [options]
```

**Examples:**

```bash
# Interactive initialization
kici init

# Overwrite existing setup
kici init --force

# Skip dependency install (faster, install manually later)
kici init --skip-install

# Force a specific package manager (default: detect from your repo)
kici init --package-manager pnpm

# JavaScript mode (no TypeScript)
kici init --mjs

# Integrate into the surrounding workspace (workflows can import sibling packages)
kici init --workspace

# Force a self-contained .kici/ even inside a workspace
kici init --standalone

# Skip writing the AGENTS.md LLM authoring context file
kici init --no-agents-md

# Scaffold a workflow registries entry for a private npm registry
kici init --private-registry https://npm.pkg.github.com/ \
          --private-registry-scope @my-org \
          --private-registry-secret production:GITHUB_PACKAGES_TOKEN
```

**What it creates:**

```
.kici/
  workflows/
    hello-world.ts    # Minimal push workflow
    pr-checks.ts      # Comprehensive PR workflow
  tests/
    push-test.ts      # Sample test fixture
  types/              # Directory for generated type declarations (kici types)
  package.json        # Dependencies (@kici-dev/sdk)
  tsconfig.json       # TypeScript configuration (includes types/**/*.d.ts)
  .gitignore          # Keeps the generated types/ declarations untracked
  .kiciignore         # Paths the workflow content hash does not cover
  AGENTS.md           # LLM authoring context (skip with --no-agents-md)
.kiciignore           # Default exclusion patterns for test uploads
```

The two `.kiciignore` files are unrelated. The one inside `.kici/` declares which paths the per-workflow content hash skips — see [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/#files-the-content-hash-skips-kicikiciignore). The one at the repo root selects which working-tree files a remote run uploads. Neither is overwritten when it already exists.

`AGENTS.md` is written by default (the interactive prompt defaults to yes, and CI / non-interactive runs write it). An existing `.kici/AGENTS.md` is never overwritten, so hand edits survive a re-run.

In interactive mode (TTY), `kici init` prompts you to:

1. Select which workflow templates to include
2. Optionally install a pre-commit hook

**Host-OS runsOn:** the scaffolded workflows target `kici:os:<your OS>` — `kici init` detects the host operating system (like it detects the default branch) and writes `kici:os:linux`, `kici:os:macos`, or `kici:os:windows` so your very first `kici run push --local` dispatches on this machine. A workflow authored on one OS and run locally on another prints a hint naming the OS it wants versus the host it found.

**First run:** in interactive mode, after setup `kici init` offers to run the scaffolded workflow immediately (`kici run push --local`), defaulting to No. It is skipped in CI, non-interactive shells, `--mjs`, and `--skip-install` (where dependencies are not installed yet).

**Package manager:** the dependency install step uses the package manager detected for your repo — the `packageManager` field in the nearest `package.json` (Corepack convention), then a lockfile in the project root (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm), then the package manager that invoked `kici` (`pnpm dlx` / `yarn dlx` / `npx`), defaulting to npm. Pass `--package-manager <npm|pnpm|yarn>` to override detection, or `--skip-install` to set up the files and install later yourself.

**Standalone vs workspace integration:** by default `kici init` scaffolds a self-contained `.kici/` with its own `package.json`. When run inside a pnpm, npm, or yarn workspace, it offers an **integrate** option (or pass `--workspace`): `.kici/` joins the workspace, `@kici-dev/sdk` is added to your workspace-root `package.json`, and your workflows can `import` your other workspace packages (e.g. shared build or deploy utilities). In this mode there is no `.kici/package.json` — the workspace root manages dependencies, and the root install resolves the SDK. Your workflows resolve sibling packages through the workspace-root `node_modules`: under npm and yarn every workspace member is hoisted there automatically, while pnpm links only your root's declared dependencies, so under pnpm add the package you want to import to your workspace-root `dependencies` (this is how KiCI's own repository imports its packages from workflows). Pass `--standalone` to force the self-contained layout even inside a workspace. In CI / non-interactive runs the default is standalone; use `--workspace` to opt in explicitly. `--workspace` and `--standalone` are mutually exclusive, and `--workspace` errors if no workspace is found at or above the current directory.

**Development mode:** When `KICI_DEV=true` or `package.json` has `"kici": { "development": true }`, the generated `package.json` pins `@kici-dev/sdk` to the `latest` dist-tag so npm resolves Verdaccio's newest prerelease build.

### kici org

Manage organization context. Requires a PAT (run `kici login` first).

#### kici org list

List organizations you belong to. The active org is marked with a star (`*`).

```bash
kici org list
```

**Example output:**

```
Organizations:

  * Personal          (owner)  abc123def456
    My team           (admin)  xyz789ghi012
```

#### kici org use

Switch the active organization by name (case-insensitive) or ID.

```bash
kici org use <name>
```

**Examples:**

```bash
# Switch by name
kici org use "My team"

# Switch by ID
kici org use xyz789ghi012
```

#### kici org current

Show the current active organization.

```bash
kici org current
```

### kici pat create

Mint a personal access token under your own identity. Pass `--agent` to mint an
**agent-kind** PAT — the credential a coding agent points the KiCI MCP server at.

```bash
kici pat create --agent --name "claude-code"
```

- `--agent` marks the token as agent-kind. An agent PAT inherits your
  permissions unchanged (it carries provenance, not extra authority) and is the
  **only** credential the MCP server accepts.
- `--name <label>` sets the token name. For an agent PAT this is the **agent
  label** recorded on every action the agent takes — required with `--agent`.
- `--expires-in-days <n>` overrides the default expiry.

The token is printed once — save it immediately; it cannot be retrieved later.
See [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/) for the full setup.

**Prerequisites:** authenticate via `kici login` first.

### kici secrets list

List secret contexts available for test runs. Shows context names and key names (not values).

```bash
kici secrets list
```

Each context corresponds to a context configured on the orchestrator. The output lists every context whose `allowLocalExecution` flag is `true` (the gate that lets CLI-initiated test runs resolve secrets through that context), along with the secret key names reachable from the context's bound scopes.

Only key names are shown — secret values are never returned over this endpoint.

**Prerequisites:** authenticate via `kici login` and select an active organization with `kici org use <name>`.

### kici admin

Operator-facing commands for running instances.

#### kici admin drain-worker

Trigger graceful drain on a worker instance. Sends a POST request to the worker's `/drain` endpoint.

```bash
kici admin drain-worker [options]
```

**Examples:**

```bash
# Drain a local worker
kici admin drain-worker --url http://localhost:10143

# Drain a remote worker
kici admin drain-worker --url http://worker-2.internal:10143
```

**Exit codes:**

| Code | Meaning                             |
| ---- | ----------------------------------- |
| 0    | Drain request accepted              |
| 1    | Error (unreachable or request fail) |

### kici endpoints

List all webhook entrypoints for the current project. Reads the compiled lock file and displays webhook URLs grouped by type (git provider, generic webhooks, scheduled, event-driven).

```bash
kici endpoints [options]
```

**Prerequisites:** Run `kici compile` first to generate the lock file.

**Examples:**

```bash
# List all webhook entrypoints
kici endpoints

# Custom .kici directory
kici endpoints --kici-dir packages/app/.kici
```

## Reference

<!-- BEGIN GENERATED: kici-account-and-org (do not edit; run the doc generator) -->

### `kici admin`

Operator-facing commands for running instances

Synopsis: `kici admin`

### `kici admin drain-worker`

Trigger graceful drain on a worker instance

Synopsis: `kici admin drain-worker [options]`

**Options**

| Option        | Default | Description                                  |
| ------------- | ------- | -------------------------------------------- |
| `--url <url>` |         | Worker URL (e.g., http://worker-host:<port>) |

### `kici endpoints`

List all webhook entrypoints for the current project

Synopsis: `kici endpoints [options]`

**Options**

| Option              | Default | Description             |
| ------------------- | ------- | ----------------------- |
| `--kici-dir <path>` | `.kici` | Path to .kici directory |

### `kici init`

Initialize .kici/ directory with default workflows

Synopsis: `kici init [options]`

**Options**

| Option                             | Default                | Description                                                                                         |
| ---------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------- |
| `--force`                          | `false`                | Overwrite existing .kici/ directory                                                                 |
| `--skip-install`                   | `false`                | Create files without installing dependencies                                                        |
| `--package-manager <npm            | pnpm                   | yarn>`                                                                                              |     | Force a package manager for the install step (default: auto-detect) |
| `--mjs`                            | `false`                | JavaScript-only mode (no TypeScript, no dependencies)                                               |
| `--workspace`                      | `false`                | Integrate .kici/ into the detected pnpm/npm/yarn workspace so workflows can import sibling packages |
| `--standalone`                     | `false`                | Force a self-contained .kici/ even inside a workspace                                               |
| `--no-agents-md`                   |                        | Skip writing .kici/AGENTS.md (LLM authoring context)                                                |
| `--private-registry <url>`         |                        | Scaffold a workflow registries: entry pointing at <url>                                             |
| `--private-registry-scope <scope>` |                        | Optional npm package scope (e.g. @my-org) for the private registry                                  |
| `--private-registry-secret <ref>`  | `production:NPM_TOKEN` | Qualified secret reference (env:NAME) the private registry token comes from                         |

### `kici login`

Authenticate with KiCI via browser OAuth (default) or API key (--token)

Synopsis: `kici login [options]`

**Options**

| Option                      | Default | Description                                                                         |
| --------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `--token <key>`             |         | API key for direct authentication (legacy)                                          |
| `--device`                  |         | Force device authorization flow (for headless/SSH environments)                     |
| `--platform-endpoint <url>` |         | Platform relay URL                                                                  |
| `--oidc-issuer <url>`       |         | OIDC issuer URL (defaults to the hosted KiCI IdP unless a flag/env selects another) |
| `--routing-key <key>`       |         | Routing key for webhook source identification                                       |
| `--no-attach`               |         | Skip the post-login prompt to attach the local dev plane                            |

### `kici logout`

Revoke PAT and clear local credentials

Synopsis: `kici logout`

### `kici orchestrators`

Inspect the org's orchestrator clusters and pick a default for run remote

Synopsis: `kici orchestrators`

### `kici orchestrators list`

List the connected orchestrator clusters for the active org

Synopsis: `kici orchestrators list [options]`

**Options**

| Option       | Default | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| `--org <id>` |         | Target organization (overrides the active org) |

### `kici orchestrators use`

Set the per-org default orchestrator cluster for run remote

Synopsis: `kici orchestrators use <name> [options]`

**Arguments**

| Argument | Required | Variadic | Description               |
| -------- | -------- | -------- | ------------------------- |
| `name`   | yes      | no       | Orchestrator cluster name |

**Options**

| Option       | Default | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| `--org <id>` |         | Target organization (overrides the active org) |

### `kici org`

Manage organizations

Synopsis: `kici org`

### `kici org current`

Show current active organization

Synopsis: `kici org current`

### `kici org list`

List organizations you belong to

Synopsis: `kici org list`

### `kici org use`

Switch active organization

Synopsis: `kici org use <name>`

**Arguments**

| Argument | Required | Variadic | Description             |
| -------- | -------- | -------- | ----------------------- |
| `name`   | yes      | no       | Organization name or ID |

### `kici pat`

Manage personal access tokens

Synopsis: `kici pat`

### `kici pat create`

Mint a personal access token (use --agent for a coding-agent token)

Synopsis: `kici pat create [options]`

**Options**

| Option                  | Default | Description                                    |
| ----------------------- | ------- | ---------------------------------------------- |
| `--name <name>`         |         | Token name (defaults to the agent label)       |
| `--agent`               | `false` | Mint an agent-kind PAT for the KiCI MCP server |
| `--expires-in-days <n>` |         | Custom expiry in days                          |

### `kici secrets`

Manage secrets

Synopsis: `kici secrets`

### `kici secrets list`

List test-available secret contexts

Synopsis: `kici secrets list`
<!-- END GENERATED: kici-account-and-org -->

---

## kici: notifications & diagnostics

Source: https://docs.kici.dev/user/cli/notifications-and-diagnostics/

## Guide

### kici notifications

Manage your organization's notification configuration — channels, subscriptions, and the Slack-identity roster — programmatically, under your PAT against the hosted Platform's org-scoped API. Requires a PAT (run `kici login` first) and an active org (`kici org use <name>`, or pass `--org <id>` to any subcommand). These are the same operations the dashboard Notifications tab performs.

Every `list` supports `--json` for machine-readable output.

#### kici notifications channels

Manage the destinations a notification is delivered to (Slack or email).

```bash
# List channels
kici notifications channels list
kici notifications channels list --json

# Add a Slack channel
kici notifications channels add --type slack --name "alerts" \
  --connection <connectionId> --slack-channel <slackChannelId>

# Add an email channel
kici notifications channels add --type email --name "email" \
  --from-name "KiCI CI" --reply-to ci@example.com

# Remove a channel
kici notifications channels remove <channelId>
```

#### kici notifications subscriptions

Manage which runs notify which channel, with optional literal `--mentions` and digest accumulation.

```bash
# List subscriptions
kici notifications subscriptions list

# Notify a channel on any failure across the org
kici notifications subscriptions add --channel <channelId> --on-status failed

# Scope to a repo, mention people, and accumulate a digest over 30s
kici notifications subscriptions add --channel <channelId> \
  --on-status failed --repo-glob 'my-org/*' \
  --mentions U012ABCDEF,U345GHIJKL --accumulate-for 30000

# Remove a subscription
kici notifications subscriptions remove <subscriptionId>
```

Key options for `add`: `--level <run|job>` (default `run`), `--scope <org|team|user|actor>` (default `org`; `--scope-id` is required for `team`/`user`), `--on-status <csv>` (required), `--repo-glob` / `--workflow-glob` / `--job-glob`, `--mentions <csv>`, `--recipient-override <csv>`, `--on-failure-class <csv>`, `--accumulate-for <ms>`.

#### kici notifications roster

Manage the Slack-identity roster used for best-effort actor tagging — mapping the person who triggered a run to a Slack member id.

`roster add` requires the `notifications:admin` permission — it is the admin editor for the shared roster. To connect **your own** Slack account (no admin needed), use **Connect Slack** on the dashboard's personal Notifications tab, which runs Sign in with Slack; there is no CLI equivalent because the flow is browser-based.

```bash
# List roster entries
kici notifications roster list

# Admin: map a contributor to their Slack member id (by id, email, or @handle)
kici notifications roster add --connection <connectionId> \
  --subject-kind git_login --subject octocat \
  --input-form email --value octocat@example.com

# Remove a roster entry (admins; or your own connected entry)
kici notifications roster remove <entryId>
```

### kici verify-attestation

Verify a KiCI build-provenance attestation bundle offline. A bundle is the signed package a workflow step produces via `ctx.attestProvenance(...)`: a DSSE-wrapped SLSA in-toto statement, the ephemeral public key that signed it, and the KiCI identity token that anchors the build context. For the end-to-end attest → verify → view journey, see the [build provenance guide](https://docs.kici.dev/user/provenance/). Verification establishes the full chain — the identity token verifies against the trusted issuer's JWKS, the DSSE signature verifies against the bundled key, and the statement's build context must match the token's claims (a mismatch is a hard failure). When an `[artifact]` is given, its SHA-256 digest is also matched against the attestation subject.

On success the output prints the **origin org** (the customer's public org id — the authoritative "who built this" the platform vouches for) and a **source marker**. A `kici run remote` attestation is flagged unmistakably: its `repository`/`ref`/`sha` are caller-supplied from a local working-tree overlay, not a triggered VCS commit, so a verifier must treat those coordinates as org-asserted rather than VCS-verified. A normal triggered run carries the ordinary `triggered` source marker. See the [build provenance guide](https://docs.kici.dev/user/provenance/) for the full trust model.

```bash
kici verify-attestation [artifact] --bundle <path-or-url> [--trust-root <url-or-file>] [options]
```

**Trust root:** `--trust-root` defaults to your **configured orchestrator** — the orchestrator you `kici login` against, which owns the provenance signing key and publishes its own JWKS (see [Which trust root do I use?](https://docs.kici.dev/user/provenance/#which-trust-root-do-i-use)), so the common case needs no flag. When no orchestrator is configured, the default falls back to the hosted KiCI platform's provenance issuer so historical platform-signed bundles still verify. The verifier never trusts the issuer named inside the token; supplying it out-of-band is what prevents a forged bundle from self-attesting. To override the default, pass `--trust-root` in one of two forms:

- **Online — an HTTPS issuer URL.** The verifier fetches `<url>/.well-known/openid-configuration`, reads its `issuer` and `jwks_uri`, and fetches the JWKS. The token's `iss` is pinned to the discovery document's `issuer`.
- **Offline — a self-contained trust-root file.** A local JSON file with the issuer and JWKS inlined, so no network access is needed (air-gapped verification):

  ```json
  {
    "issuer": "https://platform.example/issuer",
    "jwks": {
      "keys": [
        { "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "alg": "ES256", "kid": "..." }
      ]
    }
  }
  ```

**Examples:**

```bash
# Default: verify against your configured orchestrator (no --trust-root needed)
kici verify-attestation ./dist/app.tgz --bundle ./app.tgz.kici.json

# Override: verify a bundle against a specific issuer, digest-checking the artifact
kici verify-attestation ./dist/app.tgz \
  --bundle ./app.tgz.kici.json \
  --trust-root https://platform.example/issuer

# Offline / air-gapped: verify against a self-contained trust-root file
kici verify-attestation ./dist/app.tgz \
  --bundle ./app.tgz.kici.json \
  --trust-root ./kici-trust-root.json

# Machine-readable result for scripting
kici verify-attestation --bundle ./app.tgz.kici.json \
  --trust-root https://platform.example/issuer --json
```

**Attestation origin marker.** On a PASS, the command surfaces when the identity
token was minted relative to the build. A normal attestation prints no marker
(the token was minted live). A **deferred** attestation prints an `ATTESTATION:
deferred` line — the build facts were sealed at build time and the token was
minted later, after a transient platform outage, bound to the frozen statement
by its hash. An **offline-backfill** attestation prints an `ATTESTATION:
offline-backfill` line — the run was ingested while the platform was down, so its
run/job rows were backfilled before the token was minted. Both still verify
(PASS); the marker discloses the temporal gap, and the organization id remains
the authoritative anchor.

**Exit codes:**

| Code | Meaning                                                                                   |
| ---- | ----------------------------------------------------------------------------------------- |
| 0    | Verified — signature, identity, build context (and digest, if checked) all pass           |
| 1    | Not verified, or an error (missing `--bundle`, unreadable bundle, unreachable trust root) |

### kici diagnostics

Show the orchestrators, scalers, and agents serving your organization — the
terminal equivalent of the dashboard Infrastructure page. Reads the same
org-scoped data the dashboard does, so it needs `kici login` and an active org
(`kici org use <name>`).

The output has three parts: a one-line header (runs in the last 24h, success
rate, average duration, queued/running job counts), any infrastructure alerts
(only shown when present), and a tree of each orchestrator with its scalers and
agents. Each agent line shows its labels, platform/architecture, active/maximum
concurrency, and heartbeat age.

Alert lines are colored by severity — yellow for `warning`, red for `critical`.
A severity this build does not recognize is colored red, so an alert from a
newer Platform is never shown as less urgent than it might be.

```bash
kici diagnostics [options]
```

**Examples:**

```bash
# Show the full infrastructure tree
kici diagnostics

# Extended per-agent detail
kici diagnostics --verbose

# Only one orchestrator's scalers and agents
kici diagnostics --orchestrator conn-abc123

# Machine-readable output
kici diagnostics --json
```

### kici doctor

Walk your KiCI setup end to end and print the exact next command for each
problem found. Where `kici diagnostics` shows the org's infrastructure, `kici
doctor` checks **your own setup**: it runs six checks in onboarding order —
login (stored, unexpired credentials), active organization, a present, fresh,
and committed lock file, a live token probe against the platform, a connected
orchestrator for the org, and whether every workflow's `runsOn` labels are
satisfiable by a connected agent or scaler. Each check reports pass/warn/fail
with the fix command (e.g. `kici login`, `kici org use <name>`,
`kici compile`), so the first failing row tells you exactly what to run next.

```bash
kici doctor [options]
```

**Examples:**

```bash
# Diagnose the full setup
kici doctor

# Machine-readable result for scripting
kici doctor --json
```

The command exits `0` when every check passes, `1` when any check warns, and
`2` when any check fails, so it also works as a CI preflight.

### kici report

Gather a diagnostic bundle to share when you report a problem. `kici doctor`
tells you what is wrong; `kici report` packages the context somebody else needs
to see it. The bundle holds your CLI, Node and orchestrator versions, your
redacted configuration, and your project's workflow and lock-file state. With
`--run` it also holds the failing run's detail and logs.

For every orchestrator the probe returned the bundle also records where that
orchestrator's own config files live — the paths only, never the contents. An
orchestrator that is offline is still listed, with no paths: the CLI reads them
from the live connection, so a disconnected one has none to report.
Each path is a host path as that orchestrator sees it. A container deployment
names a file on the container host, which is not a file you can open from the
machine that read the bundle.

```bash
kici report [options]
```

The command writes a ZIP and prints its path and `sha256`. It does not send
anything. Open the file and read it before you share it.

```bash
# Bundle your setup
kici report

# Scope it to the run that failed, and say what went wrong
kici report --run 8f3c1d2e --message "matrix job hangs on macOS"

# Choose the output path and attach your own metadata
kici report -o /tmp/bug.zip --metadata ticket=1234 --metadata severity=high
```

**Redaction.** KiCI removes known secret shapes — API keys, tokens, `Authorization`
headers, private keys, passwords in connection URLs — from configuration and
from log text. This is best effort. A secret in a format KiCI does not
recognize can survive, so review the bundle before you share it. `--no-redact`
turns redaction off and prints a warning; use it only on a bundle you keep.

**Sending it privately.** Add `--upload` to send the bundle to KiCI over a
one-time upload link. The bundle goes straight to KiCI storage, and the command
prints a reference id to quote:

```bash
kici report --run 8f3c1d2e --upload --message "matrix job hangs on macOS"
```

Uploads are private, are kept for 90 days, and are yours to withdraw:

```bash
# See what you have sent
kici report list

# Delete an uploaded bundle
kici report withdraw <ref>
```

Anyone in your organization can upload a report. By default you see and
withdraw your own; a member with the `support:admin` permission can manage
every report in the organization.

### kici feedback

`kici report` sends a problem with **your own runs** to KiCI privately. `kici
feedback` covers the other case: a defect in KiCI itself that reproduces
without your data, such as a documented flag that does not exist.

```bash
kici feedback
```

It prints what qualifies as a reportable discrepancy, what a report must
carry, what must never appear in a public issue, and where to file it. The
command reaches no network and files nothing.

```bash
# Open the prefilled issue form in your browser
kici feedback --open

# Read the same contract as structured data
kici feedback --json
```

`--json` exists for coding agents: KiCI is built to be driven by an LLM, and
an agent can read the rules without parsing prose. One of those rules is that
an agent drafts a report and a **person** decides to file it.

The full guide is [Reporting a discrepancy](https://docs.kici.dev/user/reporting-discrepancies/).
A suspected vulnerability never goes in a public issue — follow the
disclosure process in
[SECURITY.md](https://github.com/kici-dev/kici-public/blob/main/SECURITY.md).

## Reference

<!-- BEGIN GENERATED: kici-notifications-and-diagnostics (do not edit; run the doc generator) -->

### `kici diagnostics`

Show orchestrators, scalers, and agents (mirrors the dashboard Infrastructure page)

Synopsis: `kici diagnostics [options]`

**Options**

| Option                | Default | Description                         |
| --------------------- | ------- | ----------------------------------- |
| `--json`              | `false` | Output raw JSON                     |
| `--verbose`           | `false` | Show extended per-agent fields      |
| `--orchestrator <id>` |         | Scope the tree to one connection id |

### `kici doctor`

Diagnose your KiCI setup and print the exact next command for each problem

Synopsis: `kici doctor [options]`

**Options**

| Option              | Default | Description                        |
| ------------------- | ------- | ---------------------------------- |
| `--json`            | `false` | Output raw JSON instead of a table |
| `--kici-dir <path>` | `.kici` | Path to the .kici directory        |

### `kici feedback`

Print how to report a discrepancy between what KiCI advertises and what it does. Files nothing.

Synopsis: `kici feedback [options]`

**Options**

| Option   | Default | Description                                          |
| -------- | ------- | ---------------------------------------------------- |
| `--open` |         | Open the prefilled issue form in the default browser |
| `--json` |         | Emit the reporting contract as JSON                  |

### `kici notifications`

Manage the org's notification channels, subscriptions, and Slack roster

Synopsis: `kici notifications`

### `kici notifications channels`

Manage notification channels (Slack / email)

Synopsis: `kici notifications channels`

### `kici notifications channels add`

Add a notification channel

Synopsis: `kici notifications channels add [options]`

**Options**

| Option                 | Default | Description                                    |
| ---------------------- | ------- | ---------------------------------------------- |
| `--type <slack         | email>` |                                                | Channel transport type |
| `--name <name>`        |         | Channel display name                           |
| `--connection <id>`    |         | Slack connection id (slack channels)           |
| `--slack-channel <id>` |         | Slack channel id (slack channels)              |
| `--from-name <name>`   |         | Sender name (email channels)                   |
| `--reply-to <email>`   |         | Reply-to address (email channels)              |
| `--org <id>`           |         | Target organization (overrides the active org) |

### `kici notifications channels list`

List notification channels

Synopsis: `kici notifications channels list [options]`

**Options**

| Option       | Default | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| `--org <id>` |         | Target organization (overrides the active org) |
| `--json`     |         | Output as JSON                                 |

### `kici notifications channels remove`

Remove a notification channel

Synopsis: `kici notifications channels remove <id> [options]`

**Arguments**

| Argument | Required | Variadic | Description |
| -------- | -------- | -------- | ----------- |
| `id`     | yes      | no       | Channel id  |

**Options**

| Option       | Default | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| `--org <id>` |         | Target organization (overrides the active org) |

### `kici notifications roster`

Manage the Layer 1 Slack-identity roster (actor tagging)

Synopsis: `kici notifications roster`

### `kici notifications roster add`

Add a Slack-identity roster entry

Synopsis: `kici notifications roster add [options]`

**Options**

| Option                           | Default   | Description                                    |
| -------------------------------- | --------- | ---------------------------------------------- |
| `--connection <id>`              |           | Slack connection id                            |
| `--subject-kind <kici_user       | git_login | email>`                                        |      | What the subject keys on       |
| `--subject <value>`              |           | The KiCI user sub, git login, or email         |
| `--value <slackIdEmailOrHandle>` |           | Slack member id, email, or @handle             |
| `--input-form <id                | username  | email>`                                        | `id` | How --value should be resolved |
| `--org <id>`                     |           | Target organization (overrides the active org) |

### `kici notifications roster list`

List Slack-identity roster entries

Synopsis: `kici notifications roster list [options]`

**Options**

| Option       | Default | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| `--org <id>` |         | Target organization (overrides the active org) |
| `--json`     |         | Output as JSON                                 |

### `kici notifications roster remove`

Remove a Slack-identity roster entry

Synopsis: `kici notifications roster remove <id> [options]`

**Arguments**

| Argument | Required | Variadic | Description     |
| -------- | -------- | -------- | --------------- |
| `id`     | yes      | no       | Roster entry id |

**Options**

| Option       | Default | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| `--org <id>` |         | Target organization (overrides the active org) |

### `kici notifications subscriptions`

Manage notification subscriptions

Synopsis: `kici notifications subscriptions`

### `kici notifications subscriptions add`

Add a notification subscription

Synopsis: `kici notifications subscriptions add [options]`

**Options**

| Option                       | Default | Description                                         |
| ---------------------------- | ------- | --------------------------------------------------- |
| `--channel <id>`             |         | Target channel id                                   |
| `--on-status <csv>`          |         | Statuses to notify on (e.g. failed,success)         |
| `--level <run                | job>`   | `run`                                               | Subscription granularity |
| `--scope <org                | team    | user                                                | actor>`                  | `org` | Subscription scope |
| `--scope-id <id>`            |         | Scope id (required for team/user scope)             |
| `--repo-glob <glob>`         |         | Match runs whose repo matches this glob             |
| `--workflow-glob <glob>`     |         | Match runs whose workflow matches this glob         |
| `--job-glob <glob>`          |         | Match jobs matching this glob (job level)           |
| `--mentions <csv>`           |         | Literal Slack member/group ids or emails to mention |
| `--recipient-override <csv>` |         | Override the email recipient set                    |
| `--on-failure-class <csv>`   |         | Only match these failure classes                    |
| `--accumulate-for <ms>`      |         | Digest accumulation window in milliseconds          |
| `--org <id>`                 |         | Target organization (overrides the active org)      |

### `kici notifications subscriptions list`

List notification subscriptions

Synopsis: `kici notifications subscriptions list [options]`

**Options**

| Option       | Default | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| `--org <id>` |         | Target organization (overrides the active org) |
| `--json`     |         | Output as JSON                                 |

### `kici notifications subscriptions remove`

Remove a notification subscription

Synopsis: `kici notifications subscriptions remove <id> [options]`

**Arguments**

| Argument | Required | Variadic | Description     |
| -------- | -------- | -------- | --------------- |
| `id`     | yes      | no       | Subscription id |

**Options**

| Option       | Default | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| `--org <id>` |         | Target organization (overrides the active org) |

### `kici report`

Gather a redacted diagnostic bundle to share when reporting an issue

Synopsis: `kici report [options]`

**Options**

| Option                   | Default | Description                                                  |
| ------------------------ | ------- | ------------------------------------------------------------ |
| `--run <id>`             |         | Scope the bundle to a failing run                            |
| `-o, --output <path>`    |         | Where to write the bundle ZIP                                |
| `--metadata <key=value>` |         | Attach metadata (repeatable)                                 |
| `--no-redact`            |         | Do NOT redact secrets (prints a loud warning)                |
| `--upload`               |         | Upload the bundle privately to KiCI and print a reference id |
| `--message <text>`       |         | Describe the problem (sent with --upload)                    |
| `--email <address>`      |         | Contact address for follow-up (sent with --upload)           |
| `--kici-dir <path>`      | `.kici` | Path to the .kici directory                                  |

### `kici report list`

List the issue reports you have uploaded

Synopsis: `kici report list [options]`

**Options**

| Option   | Default | Description     |
| -------- | ------- | --------------- |
| `--json` | `false` | Output raw JSON |

### `kici report withdraw`

Withdraw an uploaded report and delete its bundle

Synopsis: `kici report withdraw <ref>`

**Arguments**

| Argument | Required | Variadic | Description                            |
| -------- | -------- | -------- | -------------------------------------- |
| `ref`    | yes      | no       | Reference id of the report to withdraw |

### `kici verify-attestation`

Verify a KiCI provenance attestation bundle offline

Synopsis: `kici verify-attestation [artifact] [options]`

**Arguments**

| Argument   | Required | Variadic | Description                                                              |
| ---------- | -------- | -------- | ------------------------------------------------------------------------ |
| `artifact` | no       | no       | Artifact path to digest-check against the attestation subject (optional) |

**Options**

| Option                       | Default | Description                                                                                                                          |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--bundle <path>`            |         | Path or URL to the attestation bundle JSON                                                                                           |
| `--trust-root <url-or-file>` |         | Trusted issuer URL, or a self-contained { issuer, jwks } file (default: your configured orchestrator, else the hosted KiCI platform) |
| `--audience <aud>`           |         | Expected token audience                                                                                                              |
| `--json`                     | `false` | Output structured JSON result                                                                                                        |

<!-- END GENERATED: kici-notifications-and-diagnostics -->

---

## kici: runs & approvals

Source: https://docs.kici.dev/user/cli/runs-and-approvals/

## Guide

### kici run

Execute workflows locally or remotely. A bare `kici run [event]` performs a real routed run with this machine as the ephemeral agent; the `remote` subcommand runs fixtures through an orchestrator.

#### kici run <event> --local

Run a workflow on this machine as a real routed dispatch. `kici run <event> --local` compiles your workflows, matches triggers against the specified event, expands matrices, and executes the matched jobs — this machine joins as an ephemeral agent through the warm local dev plane. No orchestrator deployment is required.

`kici run local` (the old direct-execution subcommand) is retired: every run is now a real routed dispatch. Invoking `kici run local <event>` prints a hint pointing at `kici run <event> --local` and exits without running.

```bash
kici run [event] --local [options]
```

**Concurrency enforcement:**

A local run is a real routed dispatch, so a workflow's `concurrency` block is enforced by the local dev plane's own orchestrator — the same machinery a deployed orchestrator uses:

- The `group` callback is evaluated agent-side against the simulated event (the same `{ branch, event }` context the agent sees), and the resulting key is reported back to the plane's orchestrator before steps execute.
- `cancelInProgress: true` supersedes the older run in the group; `false` queues the newer run behind it.

Coordination is scoped to that plane, whose state lives under `~/.kici/local/` — so enforcement is per-machine and per-user, and running the same workflow on two different machines does not serialize across them. That requires a deployed orchestrator.

**Execution isolation:**

By default, `kici run <event> --local` executes steps inside an **isolated tmp checkout** rather than against your real working directory. Any file a step writes, builds, or deletes — and any `git` mutation a step performs — lands in that throwaway copy, so casual local runs never touch your tree.

What gets materialized into the isolated checkout has full parity with what `kici run remote` reconstructs: your current working tree minus gitignored files, with `.kiciignore` applied to local changes, over a real `.git` directory. Concretely, the checkout is built from a clone pinned to your current `HEAD`, with your local overlay (modified, staged, and untracked-but-not-ignored files) copied on top and locally-deleted files removed. Workflows that read git metadata work because the `.git` directory is present and pinned to your `HEAD`.

The checkout is a fresh temp directory named `kici-local-run-<random>` under the system temp directory (for example, `/tmp/kici-local-run-ab12cd`).

Cleanup policy:

- The isolated checkout is removed when the run finishes, whether it succeeded or failed.
- A hard process death (SIGKILL, OOM kill) skips that cleanup. Leftovers older than a day are swept by the agent's own startup garbage collection, which every `kici run <event> --local` invocation triggers.

Set the `KICI_TMPDIR` environment variable to place the isolated checkout (and every other KiCI-created temp directory) under a base directory other than the system temp directory.

Secrets are always sourced from your real `.kici/` directory, not from the isolated checkout. Gitignored secret files (such as `.kici/.env.local` and `.kici/secrets.yaml`) are never copied into the checkout, so a step that reads a secret still gets it from the original location.

Pass `--in-place` to run against the real working directory instead — useful when you explicitly want in-tree execution. `--in-place` requires no git repository; the default isolated mode does, and fails with an actionable error pointing at `--in-place` when the directory is not a git repository.

**If the trigger times out:**

The command waits up to 60 seconds for the local dev plane to create the run. If nothing appears in that window it stops and names the cause it read back from the plane:

| Message                                                                   | What it means                                                                                                                                                     |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plane is not leader yet (election grace period)`                         | The plane had not finished electing itself. A single-machine plane elects within seconds; if it does not, read the plane log (`kici local logs`).                 |
| `no kici.lock.json at <commit> in <path>`                                 | The plane resolved no lock file for the commit the run packed, so nothing matched. Commit `.kici/kici.lock.json`, or make sure it is present in the working tree. |
| `the plane recorded delivery <id> as "<status>"`                          | The plane processed the trigger and wrote down a terminal status for it without creating a run. The status names the stage that stopped.                          |
| `no run appeared for delivery <id> — see <log>`                           | Neither the plane's cluster state nor its delivery record explained the timeout. The named log is the next place to look.                                         |
| `no run appeared for this trigger — the plane never accepted the webhook` | Every webhook POST came back without a delivery id, so the plane never queued the trigger. Check the plane is up (`kici local status`), then read the named log.  |

**Examples:**

```bash
# Run workflows matching a push event on this machine
kici run push --local

# Run a pull-request-open workflow locally
kici run pr:open --local

# Reuse the working tree instead of an isolated clone
kici run push --local --in-place

# Force the throwaway/offline plane
kici run push --local --offline

# Environment variable overrides
kici run push --local --env NODE_ENV=test --env CI=true

# Quiet mode (summary only, no streaming)
kici run push --local --quiet
```

**Exit codes:**

| Code | Meaning                 |
| ---- | ----------------------- |
| 0    | All workflows succeeded |
| 1    | One or more jobs failed |

#### kici run remote

Execute fixtures remotely through the full CI pipeline. Fixtures are defined in `.kici/tests/*.ts` using the `fixture()` factory function. Without arguments, lists available fixtures.

Remote runs route through the Platform. Authenticate with a personal access token (`kici login`), then target an organization with `kici org use <org>` or the `--org` flag. The Platform relays the run to the org's orchestrator, while your working-tree overlay uploads directly to object storage — see [How the run is routed](https://docs.kici.dev/user/cli/runs-and-approvals/#how-the-run-is-routed) and [The two planes](https://docs.kici.dev/user/cli/runs-and-approvals/#the-two-planes) below.

Like `kici run <event> --local`, `kici run remote` recompiles your workflows (`.kici/workflows` → `kici.lock.json`) before dispatching, so the orchestrator matches and dispatches against your current workflow definitions — a brand-new or edited workflow takes effect without a separate `kici compile`. A compile or validation error aborts the run before anything is uploaded.

The orchestrator must have **cache storage configured** (`KICI_STORAGE_TYPE` = `s3` or `filesystem`) with a dev-reachable upload endpoint so the CLI's direct upload succeeds; see the [testing guide](https://docs.kici.dev/user/testing-guide/) and [Storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/) for setup.

```bash
kici run remote [fixture] [options]
```

`--approve-all` works in `--json` / `--quiet` mode: the run still auto-approves each gate it holds on, and the auto-approve diagnostics are written to stderr so stdout stays a pure JSON (or summary-only) payload. Without `--approve-all`, a `--json` / `--quiet` run that hits a gate stays held and prints a one-line "run held; approve via the dashboard or `kici approve <run-id>`" notice to stderr per hold.

**Examples:**

```bash
# List available fixtures
kici run remote

# Run a single fixture against the active org
kici run remote push-main

# Target a specific org for this run
kici run remote push-main --org xyz789ghi012

# Target a specific orchestrator cluster within the org
kici run remote push-main --orchestrator us-east

# Run all push-related fixtures
kici run remote 'push-*'

# Run everything
kici run remote --all

# Run a specific workflow directly (bypass trigger matching)
kici run remote --workflow ci

# Quiet mode -- just pass/fail
kici run remote push-main --quiet

# JSON output for scripting
kici run remote push-main --json

# Fire and forget
kici run remote push-main --no-wait

# View recent test run history
kici run remote --history

# Interactively pick which fixtures to run (multi-select)
kici run remote --pick

# Narrow runsOnAll jobs to a subset of the host roster
kici run remote deploy --target role:web

# AND-combine repeated --target values (hosts must match every selector)
kici run remote deploy --target role:web --target dc:eu

# Skip a runsOnAll job instead of failing it when the target matches no host
kici run remote deploy --target role:gpu --target-allow-empty
```

**Interactive fixture selection (`--pick` / `-p`):**

Pass `--pick` (or `-p`) to open an interactive checkbox menu of the available
fixtures. Toggle one or more with space, confirm with enter, and the selected
fixtures run through the normal remote pipeline (honoring `--parallel`,
`--no-wait`, and the other run flags). Notes:

- `--pick` is mutually exclusive with a fixture argument, `--all`, and
  `--workflow`. Passing any together exits with code 2.
- When `stdin` is not a TTY, `--pick` prints the available fixtures and exits
  without running anything — pass a fixture name (or `--all`) in scripts.

#### Host narrowing with `--target`

`--target <selector>` is a runtime narrowing for `runsOnAll` jobs, analogous to
Ansible's `--limit`. A `runsOnAll` job normally fans out to **every** roster host
matching its predicate, one pinned execution per host. `--target` intersects that
matched roster with a label selector, so the effective host set is
`runsOnAll ∩ target`:

- **Narrow-only.** `--target` can only _remove_ hosts from the matched set, never
  add them. The widening dimension (OR across host groups) lives in the workflow's
  `runsOnAll`; `--target` only subtracts.
- **Run-global, `runsOnAll`-only.** A single `--target` applies to every
  `runsOnAll` job in the run. Jobs pinned to a single host with `runsOn` are
  untouched.
- **Repeatable and AND-combined.** Each `--target` value is its own selector; a
  host must satisfy **all** of them to survive the narrowing. Use a single value
  for an OR-style match within one selector and repeated values for AND.
- **Selector syntax** matches `runsOn`: an exact label (`role:web`), a glob
  (`role:*`), or a regex (`/^box-0[1-3]$/`).

When `--target` narrows a `runsOnAll` job to zero hosts, the default is to **fail**
the run (fail-loud — a typo in the selector shouldn't silently skip work). Pass
`--target-allow-empty` to **skip** the zeroed job instead; the job records a
`skipped` status, and any downstream job that needs it with `when: 'on-skip'` (or
`when: 'always'`) still runs. See [Job dependencies](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)
for the `when` gating model.

**Exit codes:**

| Code | Meaning                      |
| ---- | ---------------------------- |
| 0    | All matched workflows passed |
| 1    | One or more workflows failed |

#### How the run is routed

A remote run is dispatched to your **active organization** — the one set with `kici org use <org>`, or overridden per-run with `--org <id>`. The org is resolved in this order:

1. The `--org <id>` flag, if provided.
2. Otherwise the active org saved in your global config by `kici org use <org>`.
3. If neither is set, the command errors and asks you to select an org with `kici org use` or pass `--org`.

The orchestrator anchors the org without any manual webhook source: it auto-provisions a system-managed **remote source** (routing key `remote:<orgId>`) that maps to its bound organization, so even a zero-source org is immediately routable for remote runs. You never set a routing key for a remote run — selecting the org is enough.

When an org has more than one connected orchestrator cluster, the CLI picks the target cluster in this order:

1. The `--orchestrator <name>` flag, if provided.
2. Otherwise the per-org default cluster, set with `kici orchestrators use <name>`.
3. If the org has exactly **one** connected orchestrator, it is auto-selected.
4. Otherwise the run errors with the list of connected clusters, and you pass `--orchestrator <name>` to choose one. Run `kici orchestrators list` to see the available cluster names.

#### The two planes

`kici run remote` uses two independent paths:

- **Control plane** — run initiation, trigger, status, log retrieval, and cancellation flow from your machine through the Platform, which relays them over a WebSocket connection to the org's orchestrator. Logs are delivered by the CLI polling the Platform for log chunks (tracked by a monotonic line cursor) and run status until the run reaches a terminal state; there is no direct streaming socket to the orchestrator.
- **Data plane** — your working-tree overlay tarball uploads **directly** from your machine to the orchestrator's object store via a presigned PUT URL. The overlay never passes through the Platform. This is why the orchestrator's object-store upload endpoint must be reachable from your machine; see [Storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/).

An orchestrator with no Platform connection cannot serve remote runs — the Platform is the service that offers them. For executing workflow steps on your own machine without an orchestrator (no scaler, agents, or environments), use [`kici run <event> --local`](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-run-event---local).

#### Fresh repos (no GitHub remote)

`kici run remote` works even if the repo has never been pushed to GitHub. When no remote is detected:

- The entire repo content is uploaded (not just a diff overlay)
- The lock file is sent inline (no GitHub API fetch)
- Steps that use git commands will fail (no `.git` directory in the remote workspace)
- Build cache (`__build__` jobs) is skipped for local repos
- Environments must have `allowLocalExecution: true` to be accessible from local runs (default is `false`)

Destination routing is unchanged for fresh repos: the run still goes to your active org through the Platform.

For a detailed guide on writing fixtures, configuring secrets, and understanding the upload flow, see [Testing guide](https://docs.kici.dev/user/testing-guide/).

#### kici orchestrators

List the orchestrator clusters connected to an organization, and set the per-org default cluster used by `kici run remote`. Requires `kici login` and an active org (or pass `--org`).

```bash
kici orchestrators list [--org <id>]
kici orchestrators use <clusterName> [--org <id>]
```

**`kici orchestrators list`** prints the org's connected orchestrator clusters, so you know what to pass to `--orchestrator` (or to `kici orchestrators use`).

**`kici orchestrators use <clusterName>`** sets the default orchestrator cluster for the org, stored per-org in your global config. Subsequent `kici run remote` invocations target that cluster unless overridden with `--orchestrator`.

**Examples:**

```bash
# List the active org's connected clusters
kici orchestrators list

# List a specific org's clusters
kici orchestrators list --org xyz789ghi012

# Set the default cluster for the active org
kici orchestrators use us-east

# Set the default cluster for a specific org
kici orchestrators use us-east --org xyz789ghi012
```

### kici runs

Inspect and manage execution runs from the terminal — the equivalent of the
dashboard Runs page. All `kici runs` subcommands read/write the same org-scoped
data as the dashboard, so they require `kici login` and an active org
(`kici org use <name>`).

#### kici runs list

List runs with optional filters. Output is a table (run id, workflow, status,
branch, trigger, started, duration); pagination is reported at the bottom.

When no runs match, `kici runs list` checks whether any webhooks arrived
recently. If deliveries came in but nothing produced a run, it prints a
one-line summary ("3 webhooks received in the last hour, 0 matched") and
suggests `kici preview push` to test your triggers locally — the fast way to
find a misconfigured trigger. When nothing arrived it prints "No runs found."
as before.

```bash
kici runs list [options]
```

```bash
kici runs list
kici runs list --status running
kici runs list --workflow ci --branch main
kici runs list --json | jq '.runs[].runId'
```

#### kici runs show

Show a run's summary header plus its jobs-and-steps tree (name, status,
duration, exit code). A run that never started a step also prints why: the
run-level failure, and per job the reason it did not run — a job a
[context](https://docs.kici.dev/user/contexts/#protection-rules) rejected names the context and the
rule. Any approval hold on the run is listed too, with its context, hold type,
status and reason. If the run id is not on the Platform but exists in your
local run history (from `kici run <event> --local`), the local record is shown instead.

```bash
kici runs show <run-id> [options]
```

```bash
kici runs show abc123
kici runs show abc123 --json
```

#### kici runs logs

Print each job/step's log lines in order, with headers.

```bash
kici runs logs <run-id> [options]
```

```bash
kici runs logs abc123
kici runs logs abc123 --job build
kici runs logs abc123 --follow
```

#### kici runs rerun

Re-trigger a completed run. Prints the new run id. The server enforces a short
cooldown between reruns of the same run.

```bash
kici runs rerun <run-id> [options]
```

```bash
kici runs rerun abc123
```

#### kici runs cancel

Cancel a single run, or all in-progress runs on a branch.

```bash
kici runs cancel [run-id] [options]
```

```bash
kici runs cancel abc123
kici runs cancel abc123 --force
kici runs cancel --branch feature/wip
```

#### kici runs artifacts list

List the [artifacts](https://docs.kici.dev/user/sdk/artifacts/) a run uploaded — name, producing job,
size, content hash, and creation time. An artifact whose stored object can no
longer be reached is flagged `unavailable`.

```bash
kici runs artifacts list <run-id> [options]
```

```bash
kici runs artifacts list abc123
kici runs artifacts list abc123 --json
```

#### kici runs artifacts download

Download a run's artifacts. Name one to fetch just that artifact; omit the name
to download every artifact of the run. Each artifact extracts into its own
`<name>/` directory by default.

```bash
kici runs artifacts download <run-id> [name] [options]
```

- `--archive` — save the raw `.tar.gz` as `<name>.tar.gz` instead of extracting.
- `-o, --output <dir>` — write into `<dir>` instead of the current directory.

```bash
kici runs artifacts download abc123 bundle
kici runs artifacts download abc123 bundle -o ./out
kici runs artifacts download abc123 --archive
kici runs artifacts download abc123
```

The download streams directly from object storage over a short-lived signed URL
— the artifact bytes never pass through the KiCI Platform — and the content hash
is verified end to end, so a corrupted or truncated transfer fails loudly rather
than leaving a bad file on disk.

Artifacts expire after the orchestrator's configured retention. When you name a
single artifact whose stored object is already gone, the command fails. When you
download the whole run, such an artifact is reported as a warning and skipped so
the remaining artifacts still land — the command fails only if every artifact of
the run was unreachable. Any other failure (a rejected signed URL, a content-hash
mismatch) stops the command immediately rather than continuing with the rest.

Artifact names are case-sensitive, so a single run can hold both `bundle` and
`Bundle`. On a filesystem that ignores case in path lookups — macOS and Windows
default to this, Linux does not — both would land on the same path, so
downloading the whole run refuses before writing anything and names the pair.
Fetch them one at a time into separate directories instead:

```bash
kici runs artifacts download abc123 bundle -o ./bundle-lower
kici runs artifacts download abc123 Bundle -o ./bundle-upper
```

Naming a single artifact is never affected, and on a case-sensitive filesystem
downloading the whole run still writes both.

Artifacts are packed relative to two roots: paths inside your repository and
paths under the home directory. Repository-relative files land directly under
`<name>/`; home-relative files land under `<name>/~home/`, so the two can never
overwrite each other and nothing is ever written outside the output directory.

When `--json` is set on any of these commands, `kici` emits only the JSON
document on stdout — the `kici v<version>` banner is suppressed — so the output
is safe to pipe into `jq` or `JSON.parse`. The same holds for the other
`--json` commands (`kici run remote --json`, `kici workflows list --json`) and
for `--quiet`.

### kici reject

Reject a held [approval gate](https://docs.kici.dev/user/approvals/). A rejection fails the held element and the run. A reason is required.

```bash
kici reject <run-id> --reason <text> [options]
```

**Examples:**

```bash
# Reject a held job with a reason
kici reject abc123 --job deploy-production --reason "Wrong release branch"
```

### kici approve

Approve a held [approval gate](https://docs.kici.dev/user/approvals/) so the run resumes. Identify the held element by run ID, optionally narrowed to a job and step.

```bash
kici approve <run-id> [options]
```

**Examples:**

```bash
# Approve a workflow-level hold
kici approve abc123

# Approve a held job
kici approve abc123 --job deploy-production

# Approve a held step (steps are addressed by index)
kici approve abc123 --job migrate-and-deploy --step 1
```

You must be eligible for at least one unsatisfied clause (a member of a named team, or a named user) and hold the permission that matches the hold's type — `ci_trust:write` for a **security** hold, `contexts:admin` for a **wait-timer** hold, `contexts:write` for every other hold. The server enforces this, so the same rule applies to the dashboard and to an AI agent's tools. The command reports whether the element was released, how many clauses remain, or that it was rejected.

## Reference

<!-- BEGIN GENERATED: kici-runs-and-approvals (do not edit; run the doc generator) -->

### `kici approve`

Approve a held approval gate for a run

Synopsis: `kici approve <run-id> [options]`

**Arguments**

| Argument | Required | Variadic | Description                           |
| -------- | -------- | -------- | ------------------------------------- |
| `run-id` | yes      | no       | Run ID whose approval gate to approve |

**Options**

| Option               | Default | Description                                                                                  |
| -------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `--job <name>`       |         | Approve the hold for a specific job                                                          |
| `--step <index>`     |         | Approve a step-scoped hold (requires --job)                                                  |
| `--hold-type <type>` |         | Approve the hold of this type (reviewer, timer, concurrency, security) — a job can carry two |
| `--hold <id>`        |         | Approve one hold by its id, as listed when nothing else separates them                       |

### `kici reject`

Reject a held approval gate for a run

Synopsis: `kici reject <run-id> [options]`

**Arguments**

| Argument | Required | Variadic | Description                          |
| -------- | -------- | -------- | ------------------------------------ |
| `run-id` | yes      | no       | Run ID whose approval gate to reject |

**Options**

| Option               | Default | Description                                                                                 |
| -------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `--job <name>`       |         | Reject the hold for a specific job                                                          |
| `--step <index>`     |         | Reject a step-scoped hold (requires --job)                                                  |
| `--hold-type <type>` |         | Reject the hold of this type (reviewer, timer, concurrency, security) — a job can carry two |
| `--hold <id>`        |         | Reject one hold by its id, as listed when nothing else separates them                       |
| `--reason <text>`    |         | Reason for the rejection                                                                    |

### `kici run`

Execute workflows locally or remotely

Synopsis: `kici run [event] [options]`

**Arguments**

| Argument | Required | Variadic | Description                                            |
| -------- | -------- | -------- | ------------------------------------------------------ |
| `event`  | no       | no       | Event type for a routed local run (e.g. push, pr:open) |

**Options**

| Option              | Default | Description                                                                                                              |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--local`           | `false` | Route the run with this machine as the ephemeral agent                                                                   |
| `--offline`         | `false` | Force the throwaway/independent plane (offline)                                                                          |
| `--connected`       | `false` | Force the connected/hybrid plane (requires attachment)                                                                   |
| `--in-place`        | `false` | Reuse the working tree directly instead of an isolated clone                                                             |
| `--trusted`         | `false` | Route to the trusted fleet agent profile: steps see the ambient host env (minus the agent identity). Alias: --no-sandbox |
| `--no-sandbox`      |         | Alias for --trusted (the bwrap sandbox is already off by default)                                                        |
| `--env <KEY=VALUE>` |         | Per-run secret (repeatable)                                                                                              |
| `--payload <path>`  |         | Dispatch payload JSON { action?, client_payload? } for a routed dispatch run                                             |
| `--kici-dir <path>` | `.kici` | Path to .kici directory                                                                                                  |
| `--quiet`           | `false` | Suppress the banner + streaming output                                                                                   |
| `--debug`           | `false` | Verbose internals                                                                                                        |

### `kici run remote`

Execute fixtures remotely via orchestrator

Synopsis: `kici run remote [fixture] [options]`

**Arguments**

| Argument  | Required | Variadic | Description                                           |
| --------- | -------- | -------- | ----------------------------------------------------- |
| `fixture` | no       | no       | Fixture name or glob pattern (omit to list available) |

**Options**

| Option                      | Default | Description                                                                                 |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `--workflow <name>`         |         | Run a specific workflow directly (bypass triggers)                                          |
| `--all`                     | `false` | Run all available fixtures                                                                  |
| `-p, --pick`                | `false` | Interactively pick fixtures to run                                                          |
| `--parallel`                | `false` | Run matching fixtures concurrently                                                          |
| `--no-wait`                 |         | Fire and forget (print runIds, don't stream)                                                |
| `--quiet`                   | `false` | Suppress output except final result                                                         |
| `--json`                    | `false` | Output structured JSON result                                                               |
| `--junit <path>`            |         | Output JUnit XML result                                                                     |
| `--history`                 | `false` | Show recent run history                                                                     |
| `--routing-key <key>`       |         | Override routing key for this run                                                           |
| `--org <id>`                |         | Target organization (overrides the active org)                                              |
| `--orchestrator <name>`     |         | Target orchestrator cluster (overrides the per-org default)                                 |
| `--debug`                   | `false` | Verbose internals                                                                           |
| `--kici-dir <path>`         | `.kici` | Path to .kici directory                                                                     |
| `--context <ctx.key=value>` |         | Inject a namespaced context secret, uploaded encrypted to the orchestrator (repeatable)     |
| `--env <KEY=VALUE>`         |         | Provide a per-run secret (repeatable); uploaded encrypted to the orchestrator               |
| `--check`                   | `false` | Run in check mode: report drift, change nothing                                             |
| `--fail-on-drift`           | `false` | In check mode, exit non-zero if any step reports drift                                      |
| `--target <selector>`       |         | Narrow runsOnAll jobs to hosts matching this label selector (repeatable, AND-combined)      |
| `--target-allow-empty`      | `false` | A --target that narrows a runsOnAll job to zero hosts skips it instead of failing           |
| `--input <KEY=VALUE>`       |         | Typed workflow-dispatch input (repeatable)                                                  |
| `--yes, --approve-all`      | `false` | Auto-approve every approval gate this run holds on (run-scoped; eligibility still enforced) |

### `kici runs`

Inspect and manage execution runs

Synopsis: `kici runs`

### `kici runs artifacts`

List and download a run's artifacts

Synopsis: `kici runs artifacts`

### `kici runs artifacts download`

Download one artifact, or all of them — extracts by default

Synopsis: `kici runs artifacts download <run-id> [name] [options]`

**Arguments**

| Argument | Required | Variadic | Description                                                |
| -------- | -------- | -------- | ---------------------------------------------------------- |
| `run-id` | yes      | no       | Run ID whose artifacts to download                         |
| `name`   | no       | no       | Artifact name (omit to download every artifact of the run) |

**Options**

| Option               | Default | Description                                   |
| -------------------- | ------- | --------------------------------------------- |
| `--archive`          | `false` | Save the raw .tar.gz instead of extracting    |
| `-o, --output <dir>` |         | Output directory (default: current directory) |

### `kici runs artifacts list`

List the artifacts a run uploaded

Synopsis: `kici runs artifacts list <run-id> [options]`

**Arguments**

| Argument | Required | Variadic | Description                    |
| -------- | -------- | -------- | ------------------------------ |
| `run-id` | yes      | no       | Run ID whose artifacts to list |

**Options**

| Option   | Default | Description     |
| -------- | ------- | --------------- |
| `--json` | `false` | Output raw JSON |

### `kici runs cancel`

Cancel a run, or all in-progress runs on a branch

Synopsis: `kici runs cancel [run-id] [options]`

**Arguments**

| Argument | Required | Variadic | Description      |
| -------- | -------- | -------- | ---------------- |
| `run-id` | no       | no       | Run ID to cancel |

**Options**

| Option            | Default | Description                                 |
| ----------------- | ------- | ------------------------------------------- |
| `--force`         | `false` | Force cancel (kill immediately, skip hooks) |
| `--branch <name>` |         | Cancel all in-progress runs on this branch  |

### `kici runs list`

List execution runs (mirrors the dashboard Runs page)

Synopsis: `kici runs list [options]`

**Options**

| Option                  | Default | Description                                               |
| ----------------------- | ------- | --------------------------------------------------------- |
| `--status <s>`          |         | Filter by status                                          |
| `--workflow <w>`        |         | Filter by workflow name                                   |
| `--branch <b>`          |         | Filter by branch/ref                                      |
| `--repo <r>`            |         | Filter by repository                                      |
| `--trigger <t>`         |         | Filter by trigger type                                    |
| `--source <routingKey>` |         | Filter by source routing key                              |
| `--since <ts>`          |         | Only runs since (ISO-8601 or epoch ms)                    |
| `--cursor <cursor>`     |         | Keyset cursor for the next page (from a prior nextCursor) |
| `--json`                | `false` | Output raw JSON                                           |

### `kici runs logs`

Print step logs for a run

Synopsis: `kici runs logs <run-id> [options]`

**Arguments**

| Argument | Required | Variadic | Description |
| -------- | -------- | -------- | ----------- |
| `run-id` | yes      | no       | Run ID      |

**Options**

| Option         | Default | Description              |
| -------------- | ------- | ------------------------ |
| `--job <name>` |         | Only logs for this job   |
| `-f, --follow` | `false` | Tail logs for a live run |
| `--json`       | `false` | Output raw JSON          |

### `kici runs rerun`

Re-trigger a run

Synopsis: `kici runs rerun <run-id> [options]`

**Arguments**

| Argument | Required | Variadic | Description     |
| -------- | -------- | -------- | --------------- |
| `run-id` | yes      | no       | Run ID to rerun |

**Options**

| Option   | Default | Description     |
| -------- | ------- | --------------- |
| `--json` | `false` | Output raw JSON |

### `kici runs show`

Show a run summary with its jobs and steps, why a job did not run, and any approval hold

Synopsis: `kici runs show <run-id> [options]`

**Arguments**

| Argument | Required | Variadic | Description       |
| -------- | -------- | -------- | ----------------- |
| `run-id` | yes      | no       | Run ID to inspect |

**Options**

| Option   | Default | Description     |
| -------- | ------- | --------------- |
| `--json` | `false` | Output raw JSON |

<!-- END GENERATED: kici-runs-and-approvals -->

---