---
title: CLI Reference
---

# CLI Reference

This page documents the command-line options exposed by Koharu's desktop binary.

Koharu uses the same binary for:

- desktop startup
- headless local Web UI
- the local HTTP API
- the built-in MCP server

## Common usage

```bash
# macOS / Linux
koharu [OPTIONS]

# Windows
koharu.exe [OPTIONS]
```

## Options

| Option | Meaning |
| --- | --- |
| `-d`, `--download` | Prefetch runtime libraries and the default vision and OCR stack, then exit |
| `--cpu` | Force CPU mode even when a GPU is available |
| `-p`, `--port <PORT>` | Bind the local HTTP server to a specific port instead of a random one |
| `--host <HOST>` | Bind the HTTP service to a specific host instead of `127.0.0.1` |
| `--headless` | Run without starting the desktop GUI |
| `--debug` | Enable debug-oriented console output |

## Behavior notes

Some flags affect more than startup appearance:

- without `--port`, Koharu chooses a random local port
- without `--host`, Koharu binds only to `127.0.0.1` so the API is reachable from the same machine only
- with `--headless`, Koharu skips the Tauri window but still serves the Web UI and API
- with `--download`, Koharu exits after dependency prefetch and does not stay running
- with `--cpu`, both the vision stack and local LLM path avoid GPU acceleration

When a fixed port is set, the main local endpoints are:

- `http://localhost:<PORT>/`
- `http://localhost:<PORT>/api/v1`
- `http://localhost:<PORT>/mcp`

## Common patterns

Start headless Web UI on a stable port:

```bash
koharu --port 4000 --headless
```

Start with CPU-only inference:

```bash
koharu --cpu
```

Download runtime packages ahead of time:

```bash
koharu --download
```

Run a local MCP endpoint on a stable port:

```bash
koharu --port 9999
```

Then connect your MCP client to:

```text
http://localhost:9999/mcp
```

Start with explicit debug logging:

```bash
koharu --debug
```

Bind to all interfaces so other machines on the local network can reach the Web UI and API:

```bash
koharu --host 0.0.0.0 --port 4000 --headless
```

This is the practical pattern for running Koharu in a container or VM where the desktop client lives on a different host. Anything other than `127.0.0.1` reachable from the network deliberately, so only set `--host` when you actually want non-loopback access.