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 Maestro.

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

Global CLI (Recommended)

dart pub global activate shepherd

As a Package

dependencies:
  shepherd: ^0.8.3

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 Maestro test flows automatically.

shepherd test gen

Shepherd Studio

The visual companion for your automation tests. Manage generated Maestro 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 Maestro YAML configurations, the shepherd_tag package must be installed and active in your Flutter project.

shepherd tag gen
Visit Shepherd Tag Site

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