01. Visão Geral

O que é o Assistant CLI?

O Assistant CLI é um wrapper de terminal modular, ultraleve e localizado escrito em Bash, projetado para orquestrar Modelos de Linguagem de Grande Porte (LLMs) locais ou em nuvem diretamente da linha de comando.

Multi-Engine Nativo

Alterne entre Antigravity, Codex, GitHub Copilot, Ollama, OpenCode e drivers customizados.

Persistência

Cada engine mantém salvo seu próprio modelo favorito. Trocar de engine nunca apaga suas escolhas anteriores.

Built-in Skills

Gere commits semânticos estruturados, resumos de projetos e READMEs completos.

Totalmente Extensível

Adicione novos prompts em Markdown, drivers shell de IA, idiomas customizados e comandos na pasta custom/.

02. Instalação & Setup

Guia de Instalação

O Assistant CLI possui instaladores otimizados para Linux, macOS e Windows (com suporte ao PowerShell via wrapper).

terminal
$curl -fsSL https://assistantcli.vercel.app/install.sh | bash
Após instalar, teste com:assistant --version
03. Início Rápido

Primeiros Passos com o Assistant CLI

Após a instalação, abra uma nova janela de terminal ou recarregue seu perfil. Teste se o comando está funcionando:

terminal
# 1. Verifique a versão instalada
assistant --version
# 2. Inspecione o status geral
assistant status
04. Modos de Uso

Modos de Interação: REPL vs One-Shot

O Assistant CLI adapta-se perfeitamente a fluxos de trabalho rápidos ou sessões iterativas profundas.

1Modo Interativo (Chat REPL)

Inicia uma sessão de chat contínuo com a engine e modelo configurados.

bash
assistant

2Modo Pergunta Direta (One-shot)

Envia a pergunta diretamente e imprime a resposta formatada no terminal.

bash
assistant "Como criar um middleware no Next.js?"
05. Gerenciamento de Engines

Arquitetura de Drivers & Multi-Engine

O Assistant CLI trata provedores de IA como drivers modulares desacoplados. Você pode alternar entre modelos em nuvem de alta capacidade ou modelos locais 100% offline com um único comando.

Comandos de Gerenciamento de Engine:

bash
# Exibe a engine ativa e modelo correspondente
assistant engine
# Abre menu interativo listando engines instaladas e não instaladas
assistant engine --list
# Troca a engine ativa imediatamente
assistant engine ollama
assistant engine agy
assistant engine opencode
# Exibe o status da engine ativa
assistant engine status
06. Modelos & Persistência

Gerenciamento de Modelos por Engine

Cada engine possui sua própria seleção de modelo salva independentemente. Quando você altera a engine de ollama para agy e depois retorna para ollama, sua preferência de modelo é restaurada perfeitamente.

bash
# Menu interativo para escolher o modelo da engine atual
assistant model --list
# Define um modelo específico para a engine ativa
assistant model set gemma4:e2b
assistant model set opencode/big-pickle
# Exibe o modelo configurado no momento
assistant model status

Persistência no Arquivo data/config.txt

Todas as preferências são salvas em formato chave-valor simples dentro de data/config.txt:

data/config.txt
ASSISTANT_ENGINE="ollama"
ASSISTANT_MODEL_AGY="gemini-3.7-flash-high"
ASSISTANT_MODEL_CODEX="codex-preview"
ASSISTANT_MODEL_COPILOT="copilot-chat"
ASSISTANT_MODEL_OLLAMA="gemma4:e2b"
ASSISTANT_MODEL_OPENCODE="opencode/big-pickle"
ASSISTANT_MODEL_OLLAMA_THINK_FLAG="--think=false"
ASSISTANT_LANG="pt-br"
ASSISTANT_CHANNEL="stable"
07. Controle de Raciocínio (Think Mode)

Think Mode para Modelos de Raciocínio (Ollama)

Modelos de raciocínio profundo (como DeepSeek R1, Qwen QwQ) costumam gerar blocos extensos de cadeia de pensamento (<think>...</think>). O Assistant CLI oferece controle granular sobre essa exibição.

Configuração Persistente

bash
# Ativa o modo de pensamento (--think)
assistant think on
# Desativa o modo de pensamento (--think=false)
assistant think off
# Oculta o pensamento da tela (--hidethinking)
assistant think hide
# Remove flags forçadas (padrão do modelo)
assistant think clear
# Exibe o status configurado
assistant think status

Flags Rápidas por Execução

bash
# Força o raciocínio profundo
assistant --think "Resolva esse algoritmo de grafos"
# Desativa o raciocínio para respostas rápidas
assistant --no-think "Gere um JSON com 3 objetos de teste"
# Oculta o bloco de raciocínio
assistant --hide-think "Explique a diferença entre mutex e semáforo"
08. Habilidades Integradas (Built-in Skills)

Skills Padrão do Assistant CLI

Assistente de Commit Semântico (assistant commit)

Git Automation

Analisa o staging do Git (git status, git diff --cached e git diff --stat) e sugere commits atômicos e padronizados seguindo a especificação Conventional Commits (feat, fix, chore, docs, refactor, test).

Exemplo de Uso
# Prepare os arquivos desejados no staging
git add src/components/Button.tsx
# Peça ao assistente para gerar a sugestão
assistant commit

Gerador de Resumos Técnicos de Projetos (assistant resume)

Portfolio & CV

Escaneia árvores de diretórios e arquivos de manifesto (package.json, Cargo.toml, pom.xml, go.mod, requirements.txt, etc.) e gera documentos estruturados em Markdown dentro do diretório ./projects-resumes/.

bash
# Analisa o diretório atual
assistant resume
# Analisa um projeto específico
assistant resume ../meu-projeto-react
# Analisa múltiplos projetos em paralelo com sub-processos
assistant resume ./app ./api ./web

Gerador de README Profissional (assistant readme)

Documentation

Analisa toda a arquitetura do projeto e cria um arquivo README.md completo com badges shields.io, sumário, guias de setup, tabelas de dependências e exemplos no idioma desejado.

bash
# Gera README em português brasileiro
assistant readme --lang pt-br --name README-PTBR
# Gera README em inglês padrão
assistant readme --lang en --name README
09. Sistema de Extensões & Customização

Extensibilidade Completa na Pasta custom/

O Assistant CLI possui uma arquitetura plug-and-play que permite criar drivers de novas ferramentas, novas skills com personas customizadas, novos idiomas de interface e comandos de terminal sem mexer no código-fonte principal.

Estrutura de Diretórios
custom/
├── engines/ # Drivers Shell (.sh) para novas ferramentas ou APIs de IA
├── locales/ # Arquivos de tradução (.sh) adicionando novos idiomas
├── skills/ # Arquivos Markdown (*-assistant.md) com personas e prompts
└── init.sh # Funções Bash para comandos dinâmicos (_cmd_<nome>)

A. Criando uma Custom Skill

Crie um arquivo Markdown seguindo a convenção custom/skills/<nome>-assistant.md ou registre via CLI:

bash
# Registrando via comando do assistente
assistant create skill revisor /caminho/para/meu-prompt.md
# Executando a nova skill criada
assistant revisor "Revise este trecho de código em Rust"

B. Criando uma Custom Engine (Driver Shell)

Crie um arquivo em custom/engines/<nome>.sh implementando o contrato de funções:

custom/engines/minha_ia.sh
# custom/engines/minha_ia.sh
_engine_minha_ia_binary() {
echo "minha-ia-cli"
}
_engine_minha_ia_is_installed() {
_is_installed "minha-ia-cli"
}
_engine_minha_ia_list_models() {
minha-ia-cli models list 2>/dev/null
}
_engine_minha_ia_run_prompt() {
local prompt="$1"
local output_file="$2"
shift 2 || true
local model=$(_get_model_for_engine "minha_ia")
if [[ -n "$output_file" ]]; then
minha-ia-cli --model "$model" -p "$prompt" > "$output_file" 2>/dev/null
else
minha-ia-cli --model "$model" -p "$prompt"
fi
}
_engine_minha_ia_run_interactive() {
local model="$1"
minha-ia-cli chat --model "$model"
}
_engine_minha_ia_default_model() {
echo "modelo-padrao"
}

C. Criando um Custom Locale (Novo Idioma)

Crie custom/locales/<lang>.sh (ex: custom/locales/fr.sh) sobrescrevendo as funções t_*:

custom/locales/fr.sh
# custom/locales/fr.sh
t_lang_changed() {
_success "Langue modifiée en: ${BOLD}$1${RESET}"
}
t_engine_status() {
_info "Moteur actuel: ${MAGENTA}${BOLD}$1${RESET}"
_info "Modèle actuel: ${GREEN}${BOLD}$2${RESET}"
}
bash
# Ativando o novo idioma no assistente
assistant lang fr

D. Comandos Shell Dinâmicos (custom/init.sh)

Adicione funções com o prefixo _cmd_<nome> no arquivo custom/init.sh:

custom/init.sh
# custom/init.sh
_cmd_docker_clean() {
echo "Limpando containers não utilizados..."
docker container prune -f
}
bash
# Executando o comando diretamente via assistant CLI
assistant docker_clean

E. Inspecionando Customizações Carregadas

bash
assistant custom status # Visão geral de todas as customizações
assistant custom engines status # Lista engines customizadas
assistant custom skills status # Lista skills customizadas
assistant custom locales status # Lista locales customizados
10. Suporte & Diagnóstico

Soluções de Problemas & Perguntas Frequentes

Respostas e soluções para os cenários e dúvidas mais comuns no dia a dia.

Soluções de Problemas & Perguntas Frequentes (FAQ)

Pronto para começar?

Instale o Assistant CLI no seu terminal em menos de 10 segundos.