🎓 Guia & Tutorial Prático da Shepherd CLI (v0.12.0)

Novo por aqui? Veja o passo a passo completo com Shell REPL, ferramentas MCP, desenvolvimento AI-Native e scaffolds.

Acessar Tutorial ➜

Shepherd CLI

Advanced automation and productivity engine via CLI for Flutter/Dart. Simplifies development workflows (clean, deploy, changelog) and connects the Design System to tests with Atomic Design and Shepherd Tag.

Architecture & Domains

+-------------------+ | Shepherd | +-------------------+ | +-----------------------------+ | | +--------+--------+ +----------+----------+ | Domains | | Functions | +-----------------+ +---------------------+ | | | | | config |<------->| Configuration | | deploy |<------->| Deploy & PRs | | init |<------->| Initialization | | domains |<------->| Business Logic | | menu |<------->| CLI UX | | tools |<------->| Utilities | | sync |<------->| Synchronizations | +-----------------+ +---------------------+
  • config - Manages project settings, environments, and users.
  • deploy - Handles release flows, PRs, and versioning.
  • init - Onboarding and project initialization.
  • domains - Business logic, entities, and use cases.
  • menu - UX/UI components for the CLI interface.
  • tools - Helpers and auxiliary services.
  • sync - Data sync, exports, and DB integrations.

Installation

Via Homebrew (macOS / Linux)

brew tap marmelotech/tap && brew install shepherd_cli

Standalone Binary (Zero Dependencies)

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

Via Dart Pub (Global CLI)

dart pub global activate shepherd

As a Package

dependencies:
  shepherd: ^0.12.1

Quick Start

Simply run `shepherd` and it will guide you through the setup.

shepherd

Configuration Modes

  • Automation only: Lightweight setup for CI/CD pipelines (clean, changelog, deploy).
  • Full DDD Setup: Complete management with domain mapping, health tracking, and team responsibility.
Fresh Team Members

Run `shepherd init` to sync your local DB with the shared `devops/domains.yaml` file.

shepherd init

Test Generation

Scans for @ShepherdTag and ShepherdPageKey annotations to generate Shepherd Tag test flows automatically.

shepherd test gen

Shepherd Studio

The visual companion for your automation tests. Manage generated Shepherd Tag flows and visualize execution results in a modern dashboard.

Explore Shepherd Studio

Atomic Stories

Organize your cycle with Atomic Design principles (atoms, molecules, organisms, tokens). Categorize UI elements to guide intelligent test generation.

# Manage User Stories
shepherd story add <id> <title> <domain> <description>
shepherd story list

# Manage Design Elements
shepherd element add <storyId> <elementId> <title> <type>
shepherd element list

# Manage Agile Tasks
shepherd task add <storyId> <title>

Shepherd Tag

Generates typed wrapper classes for your keys, ensuring UI contracts match user stories and atoms. This bridges the gap between design tokens and automated testing.

Note: To generate Shepherd Tag YAML configurations, the shepherd_tag package must be installed and active in your Flutter project.

shepherd tag gen
Visit Shepherd Tag Site

Decentralized AI & 3 Profiles

Shepherd AI brings powerful decentralized artificial intelligence directly to your terminal. With zero token surcharges, Bring Your Own Key (BYOK), and native support for local LAN inference engines, your code never leaks to third parties.

The 3 Model Profiles

  • Advanced Profile: Built for deep reasoning, architectural refactoring, complex use cases, and test suites (DeepSeek R1, Claude 3.5 Sonnet, GPT-4o).
  • Medium Profile: Fast, versatile daily driver for quick explanations, git commit messages, and everyday coding assistance (Gemini 2.5 Flash, GPT-4o-mini, Qwen 2.5).
  • Local / LAN Profile: 100% offline and private. Connects directly to Ollama, LM Studio, vLLM, or dedicated GPU machines on your local network (e.g. http://192.168.1.50:11434).

Interactive Configuration

Configure your providers, API keys, and local/LAN endpoints with an interactive guided wizard:

shepherd ai config

Command Line Usage

# Quick inquiry with automatic RAG codebase context
shepherd ai "How is the authentication domain structured?"

# Run with Advanced reasoning profile
shepherd ai "Refactor the payment usecase to follow DDD" --advanced

# Force 100% local/offline processing
shepherd ai "Analyze test coverage for this feature" --local

# Planning mode (architectural execution plan)
shepherd ai "Migrate state management to modern patterns" --plan

# Autonomous execution mode
shepherd ai "Add unit test scaffold for login_usecase" --auto

Local SQLite Vector Store & RAG

Shepherd features a zero-cloud, 100% on-device Vector Database powered by SQLite (.shepherd/vectors/embeddings.db). It turns your Dart/Flutter workspace into a searchable semantic knowledge graph without external vector hosting.

Differential Indexing

Source files are parsed into semantic chunks of ~500 tokens with 50-token overlap. Each file is tracked with an MD5 hash: only modified or newly created files are re-embedded on subsequent scans, keeping index operations instant.

Indexing Commands

# Scan and index all workspace microfrontends
shepherd ai index

# Portuguese/Spanish alias
shepherd ai indexar

# Check indexing status, total chunks, and database size
shepherd ai index --status

# Force complete re-indexing of all source code
shepherd ai index --force

# Reset and clear local vector database
shepherd ai index --clear

# Index only a specific microfrontend / package
shepherd ai index --project core_network

Interactive Shell & REPL

The Shepherd Shell is a modern interactive terminal environment with localized welcome banners (PT, EN, ES), instant slash commands, and seamless model switching.

shepherd shell

Built-in Slash Commands

  • /ai <query> - Send query to the active profile augmented by local RAG vectors.
  • /advanced, /medium, /local - Switch the active model profile on the fly.
  • /index - Inspect vector database status or trigger re-indexing.
  • /clear - Clear the current terminal buffer.
  • /help - Show trilingual command list and tips.
  • /exit - Exit the interactive shell.

Shepherd Flow (Trunk-Based Development)

Shepherd Flow is an automated release pipeline engineered for teams practicing Trunk-Based Development. It eliminates manual release friction by automating commit grouping, semantic versioning, changelog compilation, and git tagging in a single command.

🚀 Interactive Menu Integration

Accessible directly from the main CLI menu as [F] Shepherd Flow or under [4] Deploy Pipeline > [1] Shepherd Flow (TBD Releases).

Core Automations

  • Commit Grouping: Parses git log from the base branch (default: main) and categorizes commits into Features, Bug Fixes, Refactoring, and Documentation.
  • Semantic Version Bumping: Calculates next version (patch, minor, major) and updates both pubspec.yaml and lib/src/version.dart.
  • Changelog Archiving: Writes new releases into CHANGELOG.md and automatically archives older versions to changelog_history.md.
  • Direct Tagging or PRs: Supports zero-overhead direct releases (--no-pr) which automatically create and push vX.Y.Z git tags, or opens PRs via GitHub CLI (gh pr create).

CLI Commands

# Interactive Flow wizard (prompts bump type, PR vs direct release)
shepherd flow

# Automated patch release without opening a PR
shepherd flow --bump patch --no-pr

# Minor release comparing against develop branch
shepherd flow --bump minor --base develop

Project Cleanup

In monorepos or multi-package projects, cleaning every package manually is tedious. Shepherd automates this.

# Clean all registered microfrontends
shepherd clean

# Clean only the current project
shepherd clean project

Automated Changelog

Manages your `CHANGELOG.md` intelligently based on your current branch.

  • Generation Mode: In feature branches, it scans commits after `develop` and adds them to an [Unreleased] section.
  • Update Mode: In release branches, it updates the headers with the new version and date.
shepherd changelog

Deploy Pipeline

⚠️ Execution Context
  • Change: Workflow based on a specific branch where changes were made.
  • Update: Promotes the pipeline to UAT/PROD, always based on the develop branch state.

OBS: You can perform shepherd deploy and choose change from any base branch, but when moving up the environment pipeline (UAT/PROD), you must use update. 

shepherd deploy

1. Version Management

Automatically updates the application version in pubspec.yaml.

2. Active Changelog

Creates or updates CHANGELOG.md with all new features and fixes.

3. Archive History

Transfers the previous content of CHANGELOG.md to changelog_history.md, keeping the main log focused.

4. Automated PRs In Development

Initiates the Pull Request flow to the target branch (release, stage, or main) using GitHub/Azure CLI.

Domain Health

Detect architectural violations (domain leakage) and structural inconsistencies in your clean architecture.

shepherd analyze

Domain Management

Assign responsibilities and track code ownership across the organization.

# Interactive config
shepherd config

# Direct owner assignment
shepherd add-owner <domain_name>

Exporting Config

Persist your project structure as a versionable file for the team.

shepherd export-yaml