Command reference

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. Authenticate with the Kanaeru platform. See 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`

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.

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.

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.

Getting started

Core concepts

Work with Kana

Integrations

Agent machines

Kana CLI

Kana API

Command reference

Global options

`kana logout`

`kana status`

`kana auth refresh`

`kana workspace`

`kana conv`

`conv info`

`conv sessions`

`conv send <message>`

`conv history`

`conv refine`

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

`conv steer <message>`

`conv cancel`

`conv permissions`

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

`kana vision`

`kana roadmap`

`kana outcomes`

`kana tasks`

`kana artifacts`

`kana connectors`

`kana context-sources`

`kana automations`

`kana memory`

`kana skills`

`kana feedback`

`kana api`

​Global options

​Sign-in

​kana login

​kana logout

​kana status

​kana auth refresh

​kana workspace

​kana conv

​conv info

​conv sessions

​conv send <message>

​conv history

​conv refine

​conv answer <question-id> <response>

​conv steer <message>

​conv cancel

​conv permissions

​conv permission <permission-id> <action>

​kana vision

​kana roadmap

​kana outcomes

​kana tasks

​kana artifacts

​kana connectors

​kana context-sources

​kana automations

​kana memory

​kana skills

​kana feedback

​kana api

Global options

Sign-in

`kana login`

`kana logout`

`kana status`

`kana auth refresh`

`kana workspace`

`kana conv`

`conv info`

`conv sessions`

`conv send <message>`

`conv history`

`conv refine`

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

`conv steer <message>`

`conv cancel`

`conv permissions`

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

`kana vision`

`kana roadmap`

`kana outcomes`

`kana tasks`

`kana artifacts`

`kana connectors`

`kana context-sources`

`kana automations`

`kana memory`

`kana skills`

`kana feedback`

`kana api`