Initial ForgeLM import

docs/cli/commands.md

@@ -0,0 +1,235 @@
+# Referencia de comandos da CLI
+
+Esta pagina lista a superficie atual da CLI `localllm`.
+
+## Sintaxe geral
+
+```bash
+localllm [flags-globais] <comando> [subcomando] [args]
+```
+
+## Flags globais
+
+- `--server <url>`
+- `--dry-run`
+- `--api-key <token>`
+- `--models-dir <path>`
+- `--format text|json`
+
+## status
+
+Verifica o estado do backend.
+
+```bash
+localllm status
+```
+
+Uso tipico:
+
+- testar se o backend esta de pe
+- validar auth e reachability
+- integrar checks simples em scripts
+
+## models
+
+### models list
+
+Lista os modelos expostos pelo backend.
+
+```bash
+localllm models list
+```
+
+### models scan
+
+Escaneia um diretorio local de modelos.
+
+```bash
+localllm --models-dir ./models models scan
+```
+
+### models load
+
+Aceita um nome de modelo e alias opcional.
+
+```bash
+localllm models load meu-modelo.gguf --alias default
+```
+
+### models unload
+
+Aceita um modelo opcional.
+
+```bash
+localllm models unload
+localllm models unload default
+```
+
+### models use
+
+Seleciona um modelo por nome.
+
+```bash
+localllm models use default
+```
+
+### models watch
+
+Superficie prevista para acompanhar alteracoes/model lifecycle.
+
+```bash
+localllm models watch
+```
+
+### models download
+
+Aceita um repositorio como argumento.
+
+```bash
+localllm models download org/modelo
+```
+
+### models remove
+
+Remove um modelo por nome.
+
+```bash
+localllm models remove default
+```
+
+### Observacao importante sobre `models`
+
+No estado atual do projeto, a parte mais confiavel e comprovada contra o backend HTTP atual e `models list`. Os demais subcomandos devem ser tratados como superficie de operacao em evolucao, local-only ou ainda nao suportada pelo backend publico atual.
+
+## auth
+
+### auth status
+
+```bash
+localllm auth status
+```
+
+### auth enable
+
+```bash
+localllm auth enable --mode protected --api-key dev-secret
+```
+
+Modos aceitos:
+
+- `off`
+- `localonly`
+- `protected`
+
+### auth disable
+
+```bash
+localllm auth disable
+```
+
+### auth set-key
+
+```bash
+localllm auth set-key dev-secret
+```
+
+### Observacao importante sobre `auth`
+
+Os subcomandos existem na superficie da CLI, mas o backend HTTP publico atual nao expoe uma API administrativa completa para auth. Documente esses comandos como superficie de controle/planejamento, nao como garantia de operacao remota ja fechada.
+
+## config
+
+### config get
+
+```bash
+localllm config get <chave>
+```
+
+### config set
+
+```bash
+localllm config set <chave> <valor>
+```
+
+Mesma observacao de `auth`: a superficie existe, mas a administracao remota completa ainda nao esta refletida na pequena API HTTP publica atual.
+
+## bench
+
+### bench throughput
+
+Benchmark de throughput com parametros configuraveis.
+
+```bash
+localllm bench throughput --model default --samples 3 --prompt-tokens 256 --completion-tokens 128
+```
+
+Parametros atuais:
+
+- `--model` (default `default`)
+- `--samples` (default `3`)
+- `--prompt-tokens` (default `256`)
+- `--completion-tokens` (default `128`)
+
+### bench smoke
+
+```bash
+localllm bench smoke
+```
+
+### bench suite
+
+```bash
+localllm bench suite
+```
+
+### bench compare
+
+```bash
+localllm bench compare baseline candidate
+```
+
+### Observacao importante sobre `bench`
+
+O fluxo mais claramente alinhado com o backend atual e `bench throughput`.
+
+## logs
+
+Leitura de logs com limite de linhas.
+
+```bash
+localllm logs --lines 200
+```
+
+## doctor
+
+Superficie pensada para diagnostico do ambiente.
+
+```bash
+localllm doctor
+```
+
+## Exemplos com flags globais
+
+### JSON
+
+```bash
+localllm --format json status
+```
+
+### Dry run
+
+```bash
+localllm --dry-run models list
+```
+
+### Backend remoto com auth
+
+```bash
+localllm --server http://127.0.0.1:8080 --api-key dev-secret status
+```
+
+## Resumo honesto do estado atual
+
+- parser e superficie de comandos sao mais amplos que a API HTTP publica atual
+- para automacao confiavel hoje, priorize `status`, `models list` e `bench throughput`
+- use `--dry-run` quando estiver explorando comandos administrativos ainda em evolucao

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`.