> For the complete documentation index, see [llms.txt](https://kerno.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kerno.gitbook.io/docs/references/kerno-cli.md).

# Kerno CLI

### Install

The CLI is published as [`@kerno/cli`](https://www.npmjs.com/package/@kerno/cli) on npm.

```bash
npm install -g @kerno/cli
```

Or run without installing.

```bash
npx @kerno/cli <command>
```

Requires Node.js 18 or higher. For the full setup walkthrough, see the [Quickstart](/docs/getting-started/quickstart.md).

### Commands

| Command             | Description                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| `kerno init`        | Start the Kerno agent and print the MCP server configuration for your coding tool. The main entry point.       |
| `kerno stop`        | Stop the Kerno agent. Cancels in-flight tests and stops application services first.                            |
| `kerno reset`       | Stop applications, clear workspace caches, and restart the agent fresh. The escape hatch when state is stuck.  |
| `kerno status`      | Show current status.                                                                                           |
| `kerno doctor`      | Diagnose orphan agent processes and inconsistent state files. Use `--clean` to apply fixes.                    |
| `kerno logs`        | Stream workspace logs from the running agent. Use `-n <count>` to set the number of log lines (default 40).    |
| `kerno export-logs` | Export Kerno agent logs (workspace + terminal output) to a zip file. Requires `-o <path>` for the destination. |
| `kerno login`       | Log in to Kerno via your browser.                                                                              |
| `kerno logout`      | Log out from Kerno.                                                                                            |
| `kerno update`      | Update the Kerno CLI to the latest version from npm.                                                           |
| `kerno uninstall`   | Stop the agent and remove installed binaries.                                                                  |

Run `kerno` with no arguments to launch the interactive shell.

### Global options

| Option                   | Description                                        |
| ------------------------ | -------------------------------------------------- |
| `-w, --workspace <path>` | Workspace path. Defaults to the current directory. |
| `-v, --verbose`          | Show Kerno diagnostic logs.                        |
| `--force-update`         | Force re-download of the agent. Applies to `init`. |
| `-V, --version`          | Show CLI version.                                  |
| `-h, --help`             | Show help.                                         |

### `kerno init` options

| Option           | Description                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| `--headless`     | Skip the interactive UI. Enabled automatically when stdin is not a TTY, such as inside a coding agent. |
| `--force-switch` | Stop an agent bound to a different workspace and rebind to this one, without prompting.                |

The agent serves one workspace at a time. Running `kerno init` against a different repository while an agent is already bound will fail unless you pass `--force-switch`.

{% hint style="warning" %}
Rebinding to a new workspace, or restarting the agent for any reason, ends the current MCP session. Your coding tool will report an unknown session until it reconnects.
{% endhint %}

### Running inside a coding agent

`kerno status` and the bare `kerno` shell render an interactive terminal UI, which does not work in a non-interactive agent shell. When you need to check state from inside a coding agent, use `kerno --version`, `docker info`, and the `kerno_healthcheck` MCP tool instead.

### Examples

Start the agent and print MCP config.

```bash
cd /path/to/your/project
kerno init
```

Point the agent at a repository from anywhere.

```bash
kerno init -w /absolute/path/to/your/repo
```

Move the agent to a different repository.

```bash
kerno init -w /absolute/path/to/other/repo --force-switch
```

Fix orphan agent processes.

```bash
kerno doctor --clean
```

Clear workspace caches and restart cleanly.

```bash
kerno reset
```

Stream the most recent 100 log lines.

```bash
kerno logs -n 100
```

Export logs for support.

```bash
kerno export-logs -o ./kerno-logs.zip
```