Initial ForgeLM import

docs/cli/overview.md

@@ -0,0 +1,104 @@
+# 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`.