> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kanaeru.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command reference

> Every kana command, argument, and flag.

Run `kana <command> --help` for the same information in your terminal. Options placed after a subcommand belong to that subcommand, so `kana skills install --version` means the skill version, not the CLI version.

## Global options

| Option | Description |
| - | - |
| `--workspace <id>` | Use a workspace for this command only (place before the command) |
| `-V, --version` | Print the CLI version |
| `-h, --help` | Show help |

Commands that need a workspace fail with `No active workspace. Run: kana workspace use <id>`. Errors exit with code `1`.

## Sign-in

### `kana login`

Authenticate with the Kanaeru platform. See [Sign in](/cli/overview#sign-in).

| Option | Description |
| - | - |
| `--url <orchestrator-url>` | Orchestrator URL to sign in to. Without it, `kana` uses `KANAERU_ORCHESTRATOR_URL`, then the URL from the machine connection or a previous login |
| `--force` | Re-authenticate even if already logged in |
| `--device` | Approve from a browser on any device instead of a loopback redirect (SSH, containers, headless hosts) |

### `kana logout`

Log out and clear user credentials. The browser session stays signed in.

### `kana status`

Show current authentication and workspace state.

### `kana auth refresh`

Refresh an interactive login when it is near expiry.

## `kana workspace`

Manage workspaces.

| Command | Description |
| - | - |
| `workspace list [--status active\|archived] [--limit <n>] [--offset <n>]` | List workspaces in your company. Page size is 1–100 |
| `workspace get [id]` | Show workspace details. Defaults to the active workspace |
| `workspace use <id> [--local \| --global]` | Set the active workspace. `--local` stores the selection in this Git worktree; `--global` stores it in shared CLI state |
| `workspace clear-local` | Remove this Git worktree's workspace selection |
| `workspace archive <id> --yes` | Hide the workspace for all members (owner or admin only) |
| `workspace reactivate <id>` | Restore an archived workspace (owner or admin only) |

## `kana conv`

Conversation commands. Each subcommand works on the active workspace's conversation unless you pass `--conv <id>`.

### `conv info`

Show conversation details and active sessions.

### `conv sessions`

List sessions in the conversation.

### `conv send <message>`

Send a message and stream kana's reply. If the session is busy, the message is queued durably and the command exits.

| Option | Description |
| - | - |
| `--session <id>` | **Required.** Session ID to send to |
| `--runtime <type>` | Runtime type: `cc`, `codex`, `dcode`, `antigravity`, `grok`, `copilot`, `opencode`, `hermes`, `pi`, `devin`, and `cc-bedrock` (Claude Code on Bedrock, on machines signed in with AWS SSO) |
| `--machine <id>` | Machine ID. Omit it with `--runtime` to continue on the session's current machine |
| `--accept-degraded-handoff` | Allow an explicit machine handoff when the source machine is offline. Unpushed work stays on the source machine. Requires `--machine` |
| `--model <id>` | Model override advertised by the selected runtime |
| `--effort <level>` | Reasoning effort override for the selected model |
| `--no-wait` | Exit once the prompt is accepted or queued; don't wait for kana's reply |
| `--timeout <seconds>` | How long to wait for kana to finish. Default `600`, minimum `30` |

```bash theme={null}
kana conv send "Add rate limiting to the public API" --session <session-id>
```

### `conv history`

View message history.

| Option | Description |
| - | - |
| `--session <id>` | Filter by session ID |
| `--limit <n>` | Number of messages. Default `20` |

### `conv refine`

Start a new refinement session.

### `conv answer <question-id> <response>`

Answer a question from kana. Pass `--session <id>` (required) for the session that asked, and `--text` to send a free-text answer instead of choosing an option.

### `conv steer <message>`

Inject a message into a running agent mid-stream. This is the same as the **Steer** button in the web app. `--session <id>` defaults to the first active session.

### `conv cancel`

Cancel the active run, like the **Stop** button. Pass `--session <id>` to cancel one session; omit it to cancel everything in the conversation.

### `conv permissions`

Watch for pending permission requests on one session. Requires `--session <id>`; `--seconds <n>` sets the observation window (1–30, default `3`).

### `conv permission <permission-id> <action>`

Respond to a permission request, like the permission card in the web app. `<action>` is one of `allow_once`, `allow_always`, `reject_once`, `reject_always`, `cancelled`, or an option ID. `--session <id>` names the session to respond on.

## `kana vision`

| Command | Description |
| - | - |
| `vision show` | Show the workspace vision |
| `vision approve [--version <n>]` | Approve the vision, recording the version number (default `1`) |

## `kana roadmap`

| Command | Description |
| - | - |
| `roadmap list [--outcome <id>]` | List roadmap items, optionally for one outcome (ID or slug) |
| `roadmap accept <item-ids...>` | Accept proposed roadmap items |
| `roadmap reorder <item-ids...>` | Reorder roadmap items, listing IDs in the order you want |

## `kana outcomes`

Outcomes move through these phases in order: `queued`, `planning`, `review`, `execution`, `delivery`, `retro`, `completed`. A full UUID works without an active workspace; a slug needs one. See [Outcomes](/concepts/outcomes).

| Command | Description |
| - | - |
| `outcomes list [--phase <phase>]` | List outcomes |
| `outcomes get <id> [--json]` | Show outcome details |
| `outcomes transition <id> <phase>` | Move an outcome to its next phase. Only the immediate next phase is allowed |
| `outcomes replan <id> --reason <feedback>` | Send an outcome in review back to planning with your feedback (1–2000 characters) |
| `outcomes quiz-result <id> [--failed]` | Record the understanding-quiz result for an outcome |

`outcomes transition` also accepts `--quiz-passed` for `review → execution`, to attest that you passed the understanding quiz.

## `kana tasks`

| Command | Description |
| - | - |
| `tasks list [--outcome <id>] [--status <status>]` | List tasks |
| `tasks get <task-id>` | Show task details |
| `tasks approve <task-ids...>` | Approve tasks in review |

`tasks approve` checks readiness before it calls the server: requirements, journey groups, review gates, and spec coverage. If a task isn't ready, it prints what's missing.

## `kana artifacts`

Verification artifacts are the evidence an outcome produces for you to check. `<outcome-id>` accepts a UUID or slug; `<artifact-id>` accepts a full UUID or a hex prefix of at least eight characters.

| Command | Description |
| - | - |
| `artifacts list <outcome-id>` | List artifacts for an outcome |
| `artifacts approve <outcome-id> <artifact-id> [--comment <text>]` | Approve an artifact |
| `artifacts reject <outcome-id> <artifact-id> --reason <text> --question <text>` | Reject an artifact with a reason and a clarifying question |

## `kana connectors`

Discover and manage connected providers such as GitHub. Output is JSON.

| Command | Description |
| - | - |
| `connectors capabilities` | Show configured provider capabilities |
| `connectors authorize <provider>` | Get an authorization URL, then finish consent in your browser |
| `connectors install-url` | Print the Kana GitHub App install page, the only screen that can add a GitHub organization |
| `connectors connect <provider> --credentials-file <path>` | Connect provider credentials for your company from a JSON file (prefer `authorize` for OAuth providers) |
| `connectors list` | List connectors for the workspace, outcome, or session scope |
| `connectors browse <connector-id> --type <type> [--query <q>]` | Browse items a connector can see, such as repositories |
| `connectors link <connector-id> --outcome <id> --url <url> --type <type> [--label <label>]` | Link an external resource to an outcome |
| `connectors unlink <connector-id> <item-id> --outcome <id> --yes` | Remove a linked item |
| `connectors items --vision <id>` | List linked items for a vision |
| `connectors context --outcome <id>` | Read the aggregated linked context for an outcome |
| `connectors disconnect <connector-id> --yes` | Disconnect a company-wide provider (linked items stay) |

## `kana context-sources`

Manage the context sources (repositories, documents, and so on) that sessions read from, at workspace, outcome, or session scope. Output is JSON.

| Command | Description |
| - | - |
| `context-sources list [--workspace <id> \| --outcome <id> \| --session <id>]` | List sources for one scope (defaults to the active workspace) |
| `context-sources events [--workspace <id> \| --outcome <id> \| --session <id>] [--source <id>] [--cursor <c>] [--limit <n>]` | List source events |
| `context-sources add --scope <workspace\|outcome\|kana_session> --scope-id <id> --provider <type> --type <type> --url <url>` | Add a source. Optional: `--connector`, `--external-id`, `--title`, `--provider-account`, `--mode snapshot\|live`, `--event-types` |
| `context-sources pause <binding-id> --scope <s> --scope-id <id>` | Pause a source |
| `context-sources resume <binding-id> --scope <s> --scope-id <id>` | Resume a source |
| `context-sources remove <binding-id> --scope <s> --scope-id <id> --yes` | Remove a source |

## `kana automations`

Manage scheduled automations and inspect their runs. Output is JSON. See [Automations](/guides/automations).

| Command | Description |
| - | - |
| `automations list [--workspace <id>] [--limit <n>] [--offset <n>]` | List automations |
| `automations get <id>` | Show one automation |
| `automations create --file <path>` | Create an automation from a JSON file with `name`, `prompt`, `trigger`, `executionConfig`, and `scope` (plus optional `description` and `actionConfig`) |
| `automations update <id> --file <path>` | Update an automation (same keys, except `scope`) |
| `automations enable <id>` / `disable <id>` | Turn the schedule on or off |
| `automations trigger <id> [--payload-file <path>]` | Run once without enabling it |
| `automations runs <id>` | List runs |
| `automations run <id> <run-id>` | Show one run |
| `automations delete <id> --yes` | Delete permanently |

## `kana memory`

Inspect company notes and saved learnings. Kana's planning, task, review and vision sessions read company notes as company guidance. Output is JSON.

| Command | Description |
| - | - |
| `memory get` | Read company notes and who last changed each |
| `memory patterns [--workspace <id>]` | Browse saved workspace learnings and inherited company guidance |
| `memory patterns resolve <id> --reason <text> --yes` | Mark a workspace or outcome learning resolved; a recurrence reopens it |
| `memory patterns dismiss <id> --reason <text> --yes` | Dismiss a workspace or outcome learning; same-key lessons at other tiers are unchanged |
| `memory patterns reactivate <id> --reason <text> --yes` | Put a resolved workspace or outcome learning back into service |
| `memory set <key> --file <path>` | Create or replace one company note from a JSON file (owner/admin only) |
| `memory delete <key> --yes` | Delete one company note (owner/admin only) |
| `memory learnings list [--status <status>]` | List learning proposals (`candidate`, `active`, `resolved`, `dismissed`, `withdrawn`) |
| `memory learnings get <id>` | Read a proposal's evidence and revision |
| `memory learnings approve <id> --revision <hash> --reason <text> --yes` | Admit a company-wide learning |
| `memory learnings dismiss <id> --revision <hash> --reason <text> --yes` | Retire a learning and every lesson with the same key |

Reviewing learnings and changing saved learnings need the owner or admin role and a signed-in person; agent credentials are refused.

## `kana skills`

Discover and install signed Kanaeru skills into a project. These commands run inside a Kana session: they read the session from `KANA_SESSION_ID`, or you pass `--session <id>`.

| Command | Description |
| - | - |
| `skills list [--json]` | List skills authorized in the current session |
| `skills install <skill-id> [--version <v>] [--runtime <runtime>] [--offline] [--json]` | Install exactly one skill into this project |

To pin an exact build, pass `--source-commit` and `--content-sha256` together. Company skills use `--company --revision <rev> --content-sha256 <sha>`.

## `kana feedback`

Send product feedback about a Kana session and follow it up.

| Command | Description |
| - | - |
| `feedback submit <summary> --session <id>` | Send feedback. Optional: `--expected`, `--actual`, `--impact`, `--severity info\|low\|medium\|high\|critical` (default `medium`), `--route` |
| `feedback list [--session <id>] [--status <status>]` | List feedback visible to you |
| `feedback get <feedback-id>` | Show one record |
| `feedback reply <feedback-id> <message>` | Add follow-up context |

## `kana api`

A fallback that reaches any named Kanaeru API operation this CLI build knows about, for when no dedicated command exists yet.

| Command | Description |
| - | - |
| `api list` | List every named operation as `name<TAB>METHOD path` |
| `api execute <operation>` | Call one operation |

`api execute` takes `--param key=value` and `--query key=value` (both repeatable), `--body <json>` or `--body-file <path>`, and `--yes`, which is required for anything other than a `GET`.


## Related topics

- [Kana CLI](/cli/overview.md)
- [Outcomes](/concepts/outcomes.md)
- [Use Kanaeru in Codex, Claude, and ChatGPT](/mcp/connect.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.