# Visao geral da CLI

O binario `localllm` e a interface de linha de comando do projeto. Ele foi desenhado para diagnostico, automacao e operacao do backend local, com suporte a saida em texto ou JSON.

## Onde esta a CLI

- codigo: `crates/localllm-cli/src/main.rs`
- nome do binario: `localllm`

## Flags globais

As flags globais atuais sao:

- `--server` - base URL do backend, default `http://127.0.0.1:8080`
- `--dry-run` - mostra a acao planejada sem executar a chamada real
- `--api-key` - chave de auth opcional
- `--models-dir` - diretorio local de modelos, default `./models`
- `--format text|json` - formato de saida

## Superficie de comandos

Comandos raiz atuais:

- `status`
- `models`
- `auth`
- `config`
- `bench`
- `logs`
- `doctor`

## Filosofia atual

A CLI hoje mistura tres tipos de fluxo:

- comandos com execucao HTTP real contra o backend atual
- comandos locais/de operacao previstos para uma superficie maior de controle
- comandos que ja possuem parsing e planejamento, mas ainda nao estao todos ligados a uma acao remota completa

Essa distincao importa para documentacao: a CLI tem uma superficie ampla, mas a parte realmente comprovada contra o backend HTTP atual e menor.

## O que esta mais consolidado hoje

Os fluxos mais maduros no estado atual do repositorio sao:

- `status`
- `models list`
- `bench throughput`

Esses fluxos fazem mais sentido quando o backend `inference-server` esta rodando.

## Formatos de saida

### Texto

Bom para uso humano, leitura manual e diagnostico rapido.

### JSON

Bom para scripts, CI e integracoes. Use `--format json`.

## Dry run

Use `--dry-run` quando quiser validar qual URL, qual operacao ou qual tipo de acao a CLI pretende executar sem realmente disparar a operacao.

Exemplo:

```bash
cargo run -p localllm-cli -- --dry-run status
```

## Exemplos rapidos

### Verificar saude do backend

```bash
cargo run -p localllm-cli -- status
```

### Listar modelos via API

```bash
cargo run -p localllm-cli -- models list
```

### Rodar benchmark de throughput

```bash
cargo run -p localllm-cli -- bench throughput --samples 3 --prompt-tokens 256 --completion-tokens 128
```

### Usar auth

```bash
cargo run -p localllm-cli -- --api-key dev-secret status
```

## Limitacoes atuais

- nem todos os subcomandos do parser correspondem a capacidades HTTP publicas do backend atual
- a CLI foi expandida por etapas; por isso alguns comandos sao melhor entendidos como superficie de controle em evolucao
- documente e use os comandos de operacao real com mais confianca em `status`, `models list` e `bench throughput`

Para a referencia completa, siga para `commands.md`.