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 (macOS / Linux)

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

Windows (PowerShell)

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

Via Dart Pub (Global CLI)

dart pub global activate shepherd

As a Package

dependencies:
  shepherd: ^0.12.24

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, Interactive Modes & Ollama

Shepherd AI brings powerful decentralized artificial intelligence directly to your terminal. In v0.12.24, it features specialized interactive execution modes (/plan, /auto, /fast), reasoning tier control (<think> streaming), auto-discovery of local Ollama models, and zero-cost local RAG.

Interactive AI Execution Modes (/plan, /auto, /fast)

/plan [task] (--plan): Architect Mode. Directs the LLM to inspect the workspace, pinpoint affected files, assess dependencies, and generate a step-by-step implementation plan without modifying files yet.
/auto [task] (--auto): Autonomous Agent Mode. Generates full file patches (// FILE: path) and safely applies changes directly to the project codebase with preview diffs.
/fast [task] (--fast): Direct Mode. Quick, concise responses for syntax queries, terminal commands, and immediate explanations.

Reasoning Tier & <think> Streaming

Toggle reasoning scrutiny for complex architectural problems with /tier <fast|deep>. Models with native reasoning (e.g. DeepSeek-R1, o1/o3) stream their thought processes transparently inside live terminal <think> blocks.

Neutral Model Switching & Ollama Auto-Discovery

Switch between models and providers on the fly directly inside the interactive chat (/model) or from the command line. Shepherd automatically queries local Ollama daemons (/api/tags) to list and use installed local models:

# Interactive model selection menu
shepherd ai model

# Switch to local Ollama model (auto-detected, 100% private, $0 token cost)
shepherd ai model ollama qwen2.5-coder:7b

# Switch to cloud providers with native aliases
shepherd ai model claude-sonnet-5     # Anthropic Sonnet 5 default
shepherd ai model chatgpt             # OpenAI GPT-4o
shepherd ai model gemini              # Google Gemini

Interactive Configuration & BYOK

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

shepherd ai config

Command Line Usage

# Interactive conversation with mode-aware prompt ([fast] > , [plan] > , [auto] > )
shepherd ai

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

# Run with global workspace scope across all microfrontends
shepherd ai --scope workspace "Map duplicated API contracts across all microfrontends"

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

# Autonomous execution mode with safe patch application
shepherd ai "Add unit test scaffold for login_usecase" --auto

MCP (Model Context Protocol) Tools & Integration

Shepherd CLI provides native client integration for the Model Context Protocol (MCP). It bridges external developer tools, language servers (Dart/Flutter analyzers), and databases directly into interactive AI sessions with automatic tool execution and unified telemetry.

Autonomous AI Tool Execution

During interactive AI chats, agents can discover and execute MCP tools autonomously to inspect files, query schemas, run lints, and test contracts. Every invocation emits structured mcp_tool_call telemetry events to the Shepherd platform dashboard.

MCP Management Commands

# List all active MCP servers and registered tools
shepherd mcp list

# Check connection health and latency for stdio and HTTP endpoints
shepherd mcp status

# Invoke any MCP tool directly from the CLI
shepherd mcp call dart-mcp-server analyze_files --params '{"files": ["lib/main.dart"]}'

Configuration

MCP servers are configured per workspace in .shepherd/mcp.json or globally in ~/.shepherd/mcp_servers.json, supporting both local stdio subprocesses and remote http endpoints.

{
  "mcpServers": {
    "dart": {
      "command": "dart",
      "args": ["run", "dart_mcp_server"]
    }
  }
}

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 & Adaptive Policy

Source files are parsed into semantic chunks of ~500 tokens with 50-token overlap, tracked by SHA256 hashes. RAG is active by default for local models (Ollama) at zero cost ($0), and optional via --rag or /rag on for cloud models to optimize token consumption.

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 & Native Navigation

The Shepherd Shell (REPL) is an interactive terminal environment with localized welcome banners (PT, EN, ES), native directory navigation, project switching, and instant slash command execution.

shepherd shell

Native Navigation (cd, pwd, workspace)

cd <project_name> - Jump directly to any registered workspace microfrontend by name.
cd ws, cd workspace, cd root - Return immediately to the workspace root.
cd ~, cd .., cd - - Standard Unix filesystem traversal without exiting the session.
workspace or ws - List all registered projects with active folder indicators (★).
pwd - Print current working directory path.

Built-in Slash Commands

/model [name] - Dynamically switch active model (Ollama, Claude Sonnet 5, GPT-4o, Gemini).
/plan [task], /auto [task], /fast [task] - Switch execution modes on the fly.
/tier <fast|deep> - Toggle reasoning depth and <think> streaming.
/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 with dual GitHub and Azure DevOps (Azure Connect) integration.

🚀 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 (GitHub & Azure DevOps): Supports zero-overhead direct releases (--no-pr) creating and pushing vX.Y.Z git tags, or opens PRs via GitHub CLI / Azure DevOps.

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 & Safe Scanning

Deep simultaneous cleanup of builds, caches, and dependencies across all workspace microfrontends or targeted to a single project by name, with safeguards protecting macOS/Linux system folders.

# Clean all registered microfrontends in the workspace
shepherd clean

# Clean a specific microfrontend by name or path
shepherd clean AuthMicrofrontend

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

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