---
title: Referência da CLI
---

# Referência da CLI

Esta página documenta as opções de linha de comando expostas pelo binário desktop do Koharu.

O Koharu usa o mesmo binário para:

- inicialização do desktop
- Web UI local em modo headless
- a API HTTP local
- o servidor MCP embutido

## Uso comum

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

# Windows
koharu.exe [OPTIONS]
```

## Opções

| Opção | Significado |
| --- | --- |
| `-d`, `--download` | Faz o prefetch das bibliotecas de runtime e da stack padrão de visão e OCR, e então encerra |
| `--cpu` | Força o modo CPU mesmo quando uma GPU está disponível |
| `-p`, `--port <PORT>` | Vincula o servidor HTTP local a uma porta `127.0.0.1` específica em vez de uma aleatória |
| `--host <HOST>` | Vincula o serviço HTTP a um host específico em vez de `127.0.0.1` |
| `--headless` | Executa sem iniciar a GUI desktop |
| `--debug` | Habilita saída de console orientada a debug |

## Notas de comportamento

Algumas flags afetam mais do que apenas a aparência inicial:

- sem `--port`, o Koharu escolhe uma porta local aleatória
- sem `--host`, o Koharu vincula apenas a `127.0.0.1`, então a API fica acessível somente a partir da mesma máquina
- com `--headless`, o Koharu pula a janela do Tauri mas ainda serve a Web UI e a API
- com `--download`, o Koharu encerra após o prefetch de dependências e não permanece em execução
- com `--cpu`, tanto a stack de visão quanto o caminho do LLM local evitam aceleração por GPU

Quando uma porta fixa está definida, os principais endpoints locais são:

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

## Padrões comuns

Iniciar a Web UI em modo headless numa porta estável:

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

Iniciar com inferência somente em CPU:

```bash
koharu --cpu
```

Baixar os pacotes de runtime antecipadamente:

```bash
koharu --download
```

Executar um endpoint MCP local numa porta estável:

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

Depois conecte seu cliente MCP em:

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

Iniciar com logging explícito de debug:

```bash
koharu --debug
```

Vincular a todas as interfaces para que outras máquinas na rede local consigam alcançar a Web UI e a API:

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

Esse é o padrão prático para rodar o Koharu em um container ou VM, onde o cliente desktop vive em outro host. Qualquer coisa diferente de `127.0.0.1` fica acessível pela rede de forma deliberada, então só defina `--host` quando você realmente quiser acesso fora do loopback.