Tutorial da Nova Shepherd CLI v0.12.0

Passo 01

📦 Instalação Rápida Multiplataforma

A partir da versão v0.12.0, o Shepherd CLI disponibiliza binários AOT 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)

O Shepherd não é apenas uma CLI de comandos únicos: ele conta com um ambiente interativo (REPL) contínuo. Ao entrar no shell, o Shepherd detecta automaticamente se você está em um workspace ou projeto e faz o scaffold automático dos arquivos necessários.

shepherd shell

shepherd shell — v0.12.0

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

✔ Workspace detectado. Arquivos de configuração atualizados (.shepherd/mcp.json, workspace.yaml)

Digite 'help' para listar comandos disponíveis ou 'exit' para sair.

shepherd> project switch AuthMicrofrontend

➜ Contexto alterado para AuthMicrofrontend [specs.yaml carregado]

shepherd> mcp list

🔌 3 servidores conectados (flutter, dart, git) · 18 ferramentas prontas

🔄 Scaffold Automático

Mesmo em repositórios novos, o shell cria automaticamente as estruturas .shepherd/mcp.json, workspace.yaml, skills.yaml e specs.yaml.

⚡ Navegação Instantânea

Alterne entre projetos e pacotes do seu monorepo instantaneamente com project switch <nome> sem precisar abrir outros terminais.

🧠 Memória de Contexto

Comandos de IA e tarefas executadas dentro do shell preservam o histórico da sessão para análises encadeadas.

Passo 03

🔌 Conectando Servidores MCP (Model Context Protocol)

O Shepherd CLI agora possui interoperabilidade completa com o padrão MCP, compartilhando ferramentas com o Shepherd Studio Engine. Seus agentes de IA podem interagir com ferramentas do sistema, compilação, bancos de dados e APIs externas.

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 tanto processos stdio locais quanto endpoints remotos http.

Passo 04

🤖 Desenvolvimento AI-Native com Contexto Completo

O comando shepherd ai conecta seus modelos de linguagem preferidos (Gemini, Claude, GPT) ao contexto real da sua base de código, injetando esquemas de ferramentas MCP e especificações técnicas de negócio.

Modo 1: Prompt Rápido com Ferramentas

shepherd ai "Analise as rotas do projeto e sugira refatoração com base nas regras do specs.yaml"

Modo 2: Análise Global do Monorepo (--scope workspace)

shepherd ai --scope workspace "Mapeie contratos de API duplicados entre todos os microfrontends"

Modo 3: Chat Interativo Contínuo

shepherd ai # abre sessão de conversação com o modelo

Para configurar sua chave de API ou trocar o modelo padrão:

shepherd ai config

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 & Trunk-Based Development

Com a base configurada, use os comandos de automação diária para acelerar a entrega contínua sem atritos:

shepherd clean

Limpeza profunda e simultânea de builds, caches e dependências em todos os microfrontends do workspace.

shepherd flow

Fluxo automatizado de Trunk-Based Development: gera changelog semântico, bump de versão, commit e tags Git com 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