PearDrop CLI

The PearDrop CLI is the primary tool for building PearDrop applications. It handles project setup, domain scaffolding, feature injection, and database migrations.

Why Use the CLI?

The CLI automates repetitive tasks and ensures consistent code structure across your project:

• No boilerplate - Generate aggregates, commands, queries, and events instantly
• Consistent patterns - All generated code follows PearDrop conventions
• DDD-compliant - Enforces domain-driven design principles
• Type-safe - Generates strongly-typed C# code
• Migration-ready - Integrates with EF Core migrations

Installation

The CLI is pinned to your project via .config/dotnet-tools.json.

Restore it:

dotnet tool restore

Verify:

dotnet tool run peardrop --version

Add to PATH (optional):

# Windows - run once per session
$env:PATH += ";$(dotnet tool list -g | grep peardrop | awk '{print $2}')"

# Then use directly
peardrop --help

Command Categories

The CLI is organized into logical command groups:

Project Setup

Initialize new projects and modules:

• peardrop init - Create a new PearDrop project
• peardrop new project - Same as init
• peardrop new module - Create a new module
• peardrop rename module - Rename an existing module safely
• peardrop remove module - Remove a module and clean up references

→ Project Commands Guide

Domain Scaffolding

Generate domain components (aggregates, commands, queries):

• peardrop add aggregate - Create domain aggregate
• peardrop add entity - Create entity under aggregate
• peardrop add command - Create command with handler
• peardrop add query - Create query with handler
• peardrop add projection - Create read model projection
• peardrop add domain-event - Create domain event
• peardrop add integration-event - Create integration event with CAP subscriber

→ Domain Commands Guide

Feature Management

Inject features and modules into your project:

• peardrop feature - Inject authentication or multi-tenancy
• peardrop add module - Add framework modules (files, messaging)
• peardrop add email-helper - Add email service

→ Feature Commands Guide

Authentication Management

Manage authentication providers:

• peardrop auth add-entra - Add Microsoft Entra ID provider
• peardrop auth toggle-internal - Enable/disable internal auth
• peardrop auth remove-entra - Remove Entra provider
• peardrop auth list-entra - List configured providers

→ Auth Commands Guide

Utilities

Maintenance and helper commands:

• peardrop migrate - Run database migrations
• peardrop update - Update PearDrop packages
• peardrop info - Display project information
• peardrop extract-context - Extract bounded context to separate module
• peardrop cleanup - Remove temporary files

→ Utility Commands Guide

Quick Start Example

Create a new project and add your first feature:

# 1. Initialize project
peardrop init

# 2. Add an aggregate
peardrop add aggregate Equipment \
  --properties "Name:string,IsAvailable:bool,Category:string"

# 3. Add a command
peardrop add command CreateEquipment \
  --aggregate Equipment \
  --properties "Name:string,Category:string"

# 4. Add a query
peardrop add query ListEquipment \
  --returns "List<EquipmentDto>"

# 5. Create migrations
dotnet ef migrations add AddEquipment

# 6. Apply to database
peardrop migrate

Common Workflow

graph LR
    A[peardrop init] --> B[peardrop add aggregate]
    B --> C[peardrop add command]
    C --> D[Edit business logic]
    D --> E[dotnet ef migrations add]
    E --> F[peardrop migrate]
    F --> G[peardrop add query]
    G --> H[Build UI]

AI-Assisted Workflows

Projects created from the Minimal template include reusable prompt files in .github/prompts/.

• /peardrop-review-spec - clarify and annotate a feature spec
• /peardrop-tasks-from-spec - derive ordered implementation tasks
• /peardrop-validate-spec - run a final quality gate before implementation
• /peardrop-implement-spec - implement task groups with verification gates
• /peardrop-cli-workflow - plan or execute PearDrop CLI sequences safely

→ AI-Assisted Workflows Guide

Property Types Reference

All --properties flags support these types:

Type	Example	Description
string	Name:string	Text values
int	Quantity:int	32-bit integers
long	FileSize:long	64-bit integers
decimal	Price:decimal	Decimal numbers
bool	IsActive:bool	True/false values
DateTime	CreatedAt:DateTime	Date and time
DateOnly	BirthDate:DateOnly	Date without time
TimeOnly	StartTime:TimeOnly	Time without date
Guid	EquipmentId:Guid	Unique identifiers
Enum	Status:OrderStatus	Enumeration values
List<T>	Tags:List<string>	Collections

Best Practices

✅ DO

• Plan before scaffolding - Think about your aggregates and bounded contexts first
• Use specific command names - CreateEquipment not SaveEquipment
• Run migrations frequently - After each aggregate/entity change
• Implement business logic - CLI generates structure, you add the domain rules
• Use projections for queries - Separate read models from write models

❌ DON'T

• Don't skip aggregate creation - Always create aggregate before commands
• Don't leave handlers empty - Implement validation and business logic
• Don't mix aggregates - One command operates on one aggregate
• Don't forget migrations - Database and code must stay in sync
• Don't edit generated files manually - Use CLI to regenerate if needed

Troubleshooting

"peardrop: command not found"

# Restore the CLI tool
dotnet tool restore

# Or use full path
dotnet tool run peardrop --help

"Aggregate not found"

# Build project first
dotnet build

# Then try command again
peardrop add command CreateEquipment --aggregate Equipment

"Invalid property type"

Check the Property Types Reference table above. Use quotes for complex types:

peardrop add aggregate Order \
  --properties "Items:List<OrderItem>,Total:decimal"

Next Steps

• Project Commands - Set up new projects and modules
• Domain Commands - Scaffold aggregates, commands, and queries
• Feature Commands - Inject auth and other features
• Your First Project Guide - Step-by-step tutorial