File size: 2,341 Bytes
0e8f75a e706cf6 0e8f75a 15ccd87 0e8f75a 15ccd87 0e8f75a 725264a 0e8f75a 15ccd87 e706cf6 15ccd87 725264a 15ccd87 0e8f75a 15ccd87 725264a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 | ---
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.
|