CLI Commands

MediaMoth binaries use Cobra subcommands. Use this page to choose a command, then run <binary> --help and <binary> <command> --help against the exact build you deploy; the Core commands below reflect mediamoth-core/v1.0.0.

Service processes

Binary	Commands	Notes
mediamoth-core	serve, migrate, ctl	Hosts the workflow, media, job, and search APIs and their background workers in one process.
video-conversion-service	serve, worker, dual	The executable's Cobra name is video-conversion-service.
chapter-inserter	serve, worker, dual	dual runs server and worker.
vhs-service	serve <service>, worker <service>, hybrid <service>	Valid service tokens are tbc-decode and vhs-decode.

Run Core

Start every core module and its event consumers:

mediamoth-core serve

The command listens for gRPC on port 50051. It applies the combined Core database migrations before starting the server.

serve accepts these optional adapters:

Flag	Default	Meaning
--mcp	false	Start one MCP SSE server for the core API families.
--mcp-addr	:8080	MCP SSE listen address.
--mqtt	false	Enable the job module's MQTT/Mosquitto listener.

Run core migrations

Apply every pending migration before running another command against the database:

mediamoth-core migrate up

Use a positive step count to limit an up or down operation:

mediamoth-core migrate up 2
mediamoth-core migrate down 1

migrate down without a step count rolls back one migration. Core uses one migration ledger in the database's public schema and creates the module-owned schemas from the same migration set.

WARNING

Rolling migrations down changes persistent state. Back up the Core database and inspect the exact migration files in your deployed version before using migrate down.

Rebuild projections

Projection rebuilds are grouped by core module:

mediamoth-core ctl <module> rebuildProjection <handler> (--all | --aggregate-id <id>) [flags]

Module	Handlers
job	Job
media	History, Media
search	Jobs, Media, Pipelines, Services
workflow	Pipeline, Service, ServiceInfo

Useful flags:

Flag	Short	Default	Meaning
--all	-A	false	Rebuild every aggregate.
--aggregate-id	-a		Rebuild one aggregate.
--dry-run	-d	false	Resolve configuration and show the mode without replaying.
--yes	-y	false	Skip the confirmation prompt.
--db-uri		configured DB	Override the event-store URI.
--batch-size	-b	1000	Events per batch; maximum 10,000.
--count-timeout		30	Seconds allowed to count events.

WARNING

Rebuilding a projection replays stored events through its handler and can create significant database and downstream load. Start with --dry-run; omit --yes until you have reviewed the selected handler and scope.

Run module-scoped commands such as:

mediamoth-core ctl job rebuildProjection Job --all --dry-run
mediamoth-core ctl media rebuildProjection Media --aggregate-id media-123
mediamoth-core ctl search rebuildProjection Jobs --all --yes
mediamoth-core ctl workflow rebuildProjection Pipeline --aggregate-id pipeline-123

Select a VHS process

Exactly one VHS module runs per process:

vhs-service serve vhs-decode
vhs-service worker vhs-decode
vhs-service hybrid tbc-decode

The command token selects the matching section under services: in vhs-service/config.yaml.

Repository tasks

For source development, prefer mise tasks over invoking binaries manually:

mise tasks
mise run dev:mediamoth-core
mise run test:mediamoth-core
mise run lint:mediamoth-core

See Getting Started for setup.