> 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 The Kerno CLI manages the Kerno agent on your machine and sets up MCP for your coding agent. ### 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 ``` 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 ` 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 ` for the destination. | | `kerno login` | Log in to Kerno via your browser. With `--api-key `, log in without a browser and keep the key for later commands. Add `--org ` when the key belongs to several organizations. | | `kerno logout` | Log out from Kerno. | | `kerno update` | Update the Kerno CLI to the latest version from npm. Works for a global `npm install -g` install. Other installs print the command to update with. Every other command warns when a newer version is on 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 ` | Workspace path. Defaults to the current directory. | | `-v, --verbose` | Show Kerno diagnostic logs. | | `--force-update` | Force re-download of the agent. Applies to `init` and `reset`. | | `-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` | In headless mode, stop an agent bound to a different workspace and rebind to this one. | | `--org ` | Organization to use for this workspace, by name or id. Recorded, so you are not asked again. A name must match exactly one of your organizations. With an API key, this must be the key's organization, or `kerno init` stops and says how to sign in again. | | `--off` | Turn Kerno off for this workspace and exit. | | `--on` | Clear a previous `--off` for this workspace, so Kerno asks again on the next start. | One agent serves several workspaces at once. Every MCP tool takes a `workspace_path`, and that argument selects which workspace the call targets. The agent accepts the root `kerno init` started it for and any directory nested under that root, so the applications in a monorepo are separate workspaces the same agent holds at the same time. It keeps up to 5 resident, which you can raise with the `KERNO_WORKSPACE_REGISTRY_MAX_WORKSPACES` environment variable. Running `kerno init` from any other directory, including one nested under that root, rebinds the agent there. In a terminal it asks first. In headless mode it fails unless you pass `--force-switch`. `kerno init` also restarts the agent when this workspace's organization differs from the one the running agent signed in with. {% hint style="info" %} If rebinding or restarting the agent moves Kerno to a different MCP port, update your coding tool with the URL `kerno init` prints. {% endhint %} ### Environment variables | Variable | What it does | | --------------- | -------------------------------------------------------------------------------------------------------------- | | `KERNO_API_KEY` | Signs in without a browser, for CI or a remote shell. Issue the key from **Settings → API Key** in the portal. | | `KERNO_ORG_ID` | Picks the organization when your API key belongs to more than one. | ```bash export KERNO_API_KEY= kerno init -w /absolute/path/to/your/repo ``` Browser login needs a person in front of it, so use a key wherever that is not possible. See [Integrations and API keys](/docs/portal/integrations.md). The agent's port variables are covered in [Ports and file paths](/docs/references/ports-and-file-paths.md). ### Running inside a coding agent The bare `kerno` shell and `kerno login` without `--api-key` render an interactive terminal UI, which does not work in a non-interactive agent shell. `kerno status` works there. It runs its checks, prints them, and exits non-zero when one fails. `kerno --version`, `docker info`, and the `kerno_healthcheck` MCP tool also work from inside a coding agent. ### 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 ```