ForgeLM/docs/cli/overview.md

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:

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

Exemplos rapidos

Verificar saude do backend

cargo run -p localllm-cli -- status

Listar modelos via API

cargo run -p localllm-cli -- models list

Rodar benchmark de throughput

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

Usar auth

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.