CLI Commands Reference

This page provides a quick reference for MediaMoth CLI commands.

rebuildProjection

Rebuild read model projections by replaying events from the event store.

Synopsis

<service> ctl rebuildProjection <handler-name> [flags]

Description

The rebuildProjection command reads events from the event store and replays them through configured event handlers to rebuild projection data. This is useful for:

• Rebuilding projections after schema changes
• Recovering from event processing failures
• Migrating projections to new storage backends

The command overwrites projection data for each aggregate by replaying events in order.

TIP

This command can run while the service is active. Since MediaMoth uses event sourcing, rebuilds are reversible - you can rerun the projection on an older version if needed.

Prerequisites

• Access to the event store and projection database
• Database connection configured in config.yaml or provided via --db-uri

Available Services

The following services support rebuildProjection:

• job-service
• media-service
• workflow-service
• search-service

Flags

Flag	Short	Default	Description
--aggregate-id	-a		Rebuild a specific aggregate by ID
--all	-A	false	Rebuild all aggregates for the handler
--dry-run	-d	false	Preview what would be rebuilt without making changes
--yes	-y	false	Skip confirmation prompts (useful for automation)
--db-uri			PostgreSQL connection string (overrides config.yaml)
--batch-size	-b	1000	Number of events to process per batch (max: 10000)
--count-timeout		30	Timeout in seconds for counting events

Note: Either --all or --aggregate-id must be specified. They cannot be used together.

Examples

List Available Event Handlers

search-service ctl rebuildProjection --help

The help output shows all available event handlers for that service.

Rebuild All Aggregates (with Preview)

# Preview what would be rebuilt
search-service ctl rebuildProjection Jobs --all --dry-run

# Confirm and rebuild
search-service ctl rebuildProjection Jobs --all

Rebuild Single Aggregate

job-service ctl rebuildProjection Jobs --aggregate-id job-abc-123

Rebuild with Custom Database

media-service ctl rebuildProjection Media --all --db-uri "postgres://user:pass@host:5432/db"

Rebuild with Custom Batch Size

workflow-service ctl rebuildProjection Pipelines --all --batch-size 500

Automated Rebuild (Skip Confirmation)

search-service ctl rebuildProjection Jobs --all --yes

Typical Workflow

1. Check available handlers:

   service ctl rebuildProjection --help

2. Preview the rebuild (dry run):

   service ctl rebuildProjection Jobs --all --dry-run

3. Rebuild all aggregates:

   service ctl rebuildProjection Jobs --all

4. Or rebuild a single aggregate:

   service ctl rebuildProjection Jobs --aggregate-id <id>

Output

The command displays:

• Mode: all or single:<aggregate-id>
• Database connection status
• Progress bar showing amount of events completed out of total events
• Success or error message on completion

Example output:

Common Errors

Database connection failed

• Verify PostgreSQL is running
• Check connection string in config.yaml
• Ensure database credentials are correct

No events found for aggregate

• Verify the aggregate ID exists
• Check that events were written to the event store

See Also

• Event Sourcing Architecture - Deep dive on event sourcing and projections
• Search Indexing - How search projections work
• Common Issues - Troubleshooting projection problems

---

Future Commands

Additional CLI commands (serve, worker, dual) will be documented in future updates.