Tutorial da Nova Shepherd CLI v0.12.24

Passo 01

📦 Instalação Rápida Multiplataforma

Na versão v0.12.24, o Shepherd CLI é distribuído em binários AOT nativos e independentes. Você não precisa ter o Dart SDK nem o Flutter instalados na máquina para começar a usar.

brew tap marmelotech/tap && brew install shepherd_cli

curl -fsSL https://raw.githubusercontent.com/cruvinelrv/shepherd/main/scripts/install.sh | bash

irm https://raw.githubusercontent.com/cruvinelrv/shepherd/main/scripts/install.ps1 | iex

dart pub global activate shepherd

Após instalar, valide se o comando está disponível executando:

shepherd version

💡 Dica de Atualização Automática:

Você pode verificar e aplicar novas versões instantaneamente executando shepherd auto-update no terminal.

Passo 02

⚡ O Novo Shell Interativo (REPL) & Navegação Nativa

O Shepherd não é apenas uma CLI de comandos pontuais: ele conta com um ambiente interativo (REPL) contínuo. Ele detecta automaticamente workspaces DDD, faz o scaffold de configurações e agora inclui navegação nativa com cd, pwd e suporte inteligente a projetos cadastrados.

shepherd shell

shepherd shell — v0.12.24

🐑 Shepherd Interactive Shell v0.12.24 [Workspace: SuperApp]

✔ Workspace detectado. Arquivos sincronizados (.shepherd/mcp.json, workspace.yaml)

Digite 'help' para comandos, '/' para slash commands ou 'exit' para sair.

shepherd> cd AuthMicrofrontend

➜ Contexto alterado para AuthMicrofrontend [specs.yaml carregado]

shepherd> ws

📁 4 projetos registrados em workspace.yaml (AuthMicrofrontend ★, Catalog, Checkout, CoreUi)

shepherd> /model ollama

🤖 Modelo ativo: ollama:qwen2.5-coder:7b (Local RAG ativo · $0 custo de tokens)

🧭 Navegação Nativa (cd, pwd, ws)

Navegue com cd <nome_do_projeto> para pular direto para um microfrontend, cd ws para voltar à raiz do workspace, cd .. ou cd ~. Use ws para listar todos os projetos.

⚡ Interceptação de Slash Commands

Comandos com barra como /model, /plan, /auto, /fast, /tier e /help são executados instantaneamente sem serem enviados por engano como prompt para o modelo.

🔄 Scaffold & Contexto Contínuo

Gera automaticamente as estruturas .shepherd/mcp.json, workspace.yaml, skills.yaml e specs.yaml, atualizando o contexto em tempo real conforme você navega.

Passo 03

🔌 Conectando Servidores MCP & Execução Autônoma

O Shepherd CLI possui suporte nativo ao protocolo MCP (Model Context Protocol). No v0.12.24, além de invocar ferramentas manualmente, os agentes de IA podem executar ferramentas MCP autonomamente durante a conversa com telemetria unificada de ferramentas (mcp_tool_call).

Liste todos os servidores ativos e ferramentas registradas:

shepherd mcp list

Verifique o status de conexão de cada servidor (stdio e HTTP):

shepherd mcp status

Você também pode invocar qualquer ferramenta diretamente da linha de comando:

shepherd mcp call dart-mcp-server analyze_files --params '{"files": ["lib/main.dart"]}'

⚙️ Onde configurar os servidores MCP:

O Shepherd CLI carrega automaticamente os servidores definidos em .shepherd/mcp.json (no seu repositório) ou em ~/.shepherd/mcp_servers.json (global). Suporta processos stdio locais e endpoints remotos http.

Passo 04

🤖 Assistente AI v0.12.24: Modos Interativos, Ollama e RAG Local

O comando shepherd ai é o núcleo do desenvolvimento AI-Native. A versão v0.12.24 introduz modos de execução arquiteturais (/plan, /auto, /fast), controle de raciocínio com streaming de <think>, auto-descoberta de modelos locais Ollama e RAG semântico com SQLite local.

🎯 Novos Modos de Execução da IA (/plan, /auto, /fast)

📋 /plan [tarefa]

Modo Arquiteto: A IA analisa o monorepo, identifica arquivos impactados, avalia dependências e cria um plano passo a passo rigoroso sem alterar arquivos ainda.

⚡ /auto [tarefa]

Modo Agente Autônomo: A IA gera patches completos de código (// FILE: path) e aplica as alterações diretamente no workspace com confirmação segura.

🚀 /fast [tarefa]

Modo Direto: Respostas ágeis, focadas e concisas para dúvidas de código, consultas de sintaxe e comandos do terminal.

# Iniciar sessão interativa com prompt indicando o modo ativo:
shepherd ai
# Dentro do chat interativo:
[fast] > /plan Criar autenticação biométrica respeitando specs.yaml
[plan] > /auto Aplicar as alterações da etapa 1 no AuthMicrofrontend
[auto] > /tier deep  # ativa raciocínio profundo com streaming de <think>

🧠 Troca Neutra de Modelos & Auto-Descoberta Ollama

Alterne entre provedores e modelos a qualquer momento direto pelo terminal ou no chat. A CLI consulta automaticamente seu daemon local do Ollama para listar modelos já baixados:

                
                # Seleção interativa de provedores ou modelos locais:
shepherd ai model

# Troca direta por linha de comando ou via slash command no chat (/model):
shepherd ai model ollama qwen2.5-coder:7b  # 100% privado e gratuito
shepherd ai model claude-sonnet-5          # Anthropic Sonnet 5 padrão
shepherd ai model chatgpt                  # OpenAI GPT-4o
            

📚 RAG Local Adaptativo & Banco Vetorial SQLite:

Para modelos locais (Ollama), o RAG de código é ativo por padrão a custo zero ($0), injetando chunks da sua base de código sem vazar dados. Em modelos pagos de nuvem, o RAG é econômico e pode ser ligado com a flag --rag ou /rag on.

Passo 05

📐 Estrutura de Workspace, Specs e Skills

Para garantir consistência em times e arquiteturas corporativas, o Shepherd CLI padroniza arquivos declarativos em YAML que servem de guia tanto para desenvolvedores quanto para a IA:

workspace.yaml

Localizado na raiz do workspace ou em .shepherd/. Define o nome do ecossistema, os projetos filhos, microfrontends e suas dependências.

specs.yaml

Reside no nível de cada projeto/microfrontend. Descreve as regras de negócio, contratos de API e casos de uso esperados pela arquitetura.

skills.yaml

Define habilidades e instruções especializadas (ex: regras de teste com Shepherd Tag, padrões de UI Clean Architecture) injetadas no prompt da IA.

Passo 06

🚀 Automação Contínua, Limpeza Segura & Flow

Com a base configurada, use os comandos de automação diária com garantias de segurança contra pastas do sistema e integração contínua:

shepherd clean [projeto]

Limpeza profunda de caches e dependências de todo o workspace ou de um microfrontend específico por nome. Ignora com segurança pastas protegidas do macOS/Linux e detecta projetos Dart vs Flutter.

shepherd flow

Fluxo de Trunk-Based Development com suporte dual a GitHub e Azure DevOps (Azure Connect): changelog semântico, bump de versão, commit e tags Git em 1 comando.

shepherd tag gen

Gera automaticamente wrappers de tags de teste de interface a partir de anotações no código-fonte.

shepherd test gen

Cria suites de testes ponta a ponta com Shepherd Tag a partir das tags do seu design system.

Guia Prático da Nova Shepherd CLI