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¶

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

koharu --port 4000 --headless

Start with CPU-only inference:

koharu --cpu

Download runtime packages ahead of time:

koharu --download

Run a local MCP endpoint on a stable port:

koharu --port 9999

Then connect your MCP client to:

http://localhost:9999/mcp

Start with explicit debug logging:

koharu --debug

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

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.