> ## 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.

# Kana CLI

> Drive Kanaeru from your terminal: sign in, pick a workspace, talk to kana, and approve work.

`kana` is the Kanaeru command-line client. It talks to the same Kanaeru service as the web app, so anything you start in the terminal shows up in the browser and the other way round.

## Install

`kana` ships inside the Agent Manager bundle, so there is no separate package to install. When you [connect a machine](/machines/connect-a-machine), the installer puts the `kanaeru-agent-manager` and `kana` executables in your user-local binary directory (`~/.local/bin` on macOS and Linux) and adds that directory to your login `PATH`.

Supported platforms are macOS on Apple Silicon, Linux x64, and Windows x64.

```bash theme={null}
kana --version
kana --help
```

### Updates

`kana` never updates itself. After each command it checks, at most every six hours, whether Kanaeru expects a newer version. If yours is behind, it prints a notice on stderr. To update, open the machine page (`/machine-connect`, or **Connect** in the chat box's runtime selector) and choose **Upgrade agent manager**, which ships the matching `kana`.

Set `KANAERU_CLI_SKIP_UPDATE_CHECK=1` to silence the notice.

## Sign in

```bash theme={null}
kana login
```

`kana login` opens your browser on the **Connect Kanaeru CLI** page. Sign in with the same Google or Microsoft account you use for the web app, and the terminal finishes the login on its own. The browser never hands tokens to the terminal: it returns a single-use code that the CLI exchanges with a PKCE verifier only it holds.

If you're on a machine without a browser (over SSH, in a container, on a headless host), use the cross-device flow instead:

```bash theme={null}
kana login --device
```

The CLI prints a URL and a short code. Open the URL on any device, check that the page shows the same code, and choose **Authorize**.

<Warning>
  Authorizing gives that terminal full access to your Kanaeru account. If you didn't just run `kana login`, choose **Reject**.
</Warning>

Other auth commands:

| Command | What it does |
| - | - |
| `kana status` | Shows who you're signed in as, how you're signed in, token expiry, and the active workspace |
| `kana auth refresh` | Refreshes a login that's close to expiring (this also happens automatically before requests) |
| `kana logout` | Revokes this terminal's session and deletes the local credentials. Your browser session stays signed in |
| `kana login --force` | Signs in again even if you're already signed in |

### Machine credentials

A machine connected through the Agent Manager already holds a machine credential, and `kana` falls back to it when no one has run `kana login`. A personal login always takes precedence. `kana status` tells you which one is in use: **Auth: user login (kana login)** or **Auth: machine bridge (from machine connect)**. That's why a coding agent running on a connected machine can use `kana` straight away.

## Choose a workspace

Most commands act on the **active workspace**.

```bash theme={null}
kana workspace list
kana workspace use <workspace-id>
```

A selection can be scoped:

* `kana workspace use <id> --local` keeps the choice inside the current Git worktree, so different checkouts can point at different workspaces. `kana workspace clear-local` removes it.
* `kana workspace use <id> --global` stores it in the shared CLI state.
* `kana --workspace <id> <command>` uses a workspace for one command only. Put the flag before the command.

## Files and environment variables

| Path | Purpose |
| - | - |
| `~/.kanaeru/credentials.json` | Your login (tokens, email, active workspace) |
| `~/.kanaeru/config.json` | Agent Manager configuration, read-only to `kana` |
| `~/.kanaeru/cli-state.json` | Workspace, vision, and conversation selection when you're on machine credentials |
| `<git-dir>/kanaeru/cli-state.json` | Worktree-local workspace selection from `workspace use --local` |
| `~/.kanaeru/cli-update-check.json` | Update-check cache |

| Variable | Effect |
| - | - |
| `KANAERU_WORKSPACE_ID` | Workspace for this command (what `--workspace` sets) |
| `KANAERU_CLI_CREDENTIALS_FILE` | Alternate credentials file |
| `KANAERU_CONFIG` | Alternate Agent Manager config file |
| `KANAERU_CLI_STATE_FILE` | Explicit state file |
| `KANAERU_CLI_DISABLE_WORKTREE_STATE` | Ignore worktree-local workspace selection |
| `KANAERU_CLI_SKIP_UPDATE_CHECK` | Any non-empty value turns off the update notice |

## Next steps

<CardGroup cols={2}>
  <Card title="Command reference" icon="terminal" href="/cli/reference">
    Every command, argument, and flag.
  </Card>

  <Card title="Talk to kana from the terminal" icon="messages" href="/cli/reference#kana-conv">
    Send messages, steer, answer questions, and approve permission requests.
  </Card>
</CardGroup>


## Related topics

- [Use Kanaeru in Codex, Claude, and ChatGPT](/mcp/connect.md)
- [Kanaeru overview](/index.md)
- [API introduction](/api/introduction.md)


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