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 tables below reflect mediamoth main at commit 481899a.

Service processes

Binary	Commands	Notes
media-service	serve	The server includes its in-memory event handling.
workflow-service	serve, ctl	serve accepts MCP flags.
job-service	serve, ctl	serve accepts MCP and MQTT flags.
search-service	serve, worker, dual, migrate, ctl	dual runs server and worker.
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.

Media, Workflow, and Job Service no longer have a dual command. Their serve process includes the event handlers that were previously separate.

MCP and MQTT flags

Workflow, Job, Media, and Search server commands accept:

Flag	Default	Meaning
--mcp	false	Start the MCP SSE server.
--mcp-addr	:8080	MCP SSE listen address.

Job Service also accepts --mqtt to enable its Mosquitto listener.

Projection rebuilds

Job, Search, and Workflow Service expose the following command form for rebuilding one projection handler or every aggregate handled by that projection:

<service> ctl rebuildProjection <handler> (--all | --aggregate-id <id>) [flags]

Handlers differ by service:

Service	Handlers
job-service	Job
search-service	Jobs, Services
workflow-service	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 a command such as the following after choosing the service and handler:

job-service ctl rebuildProjection Job --all --dry-run
workflow-service ctl rebuildProjection Pipeline --aggregate-id pipeline-123
search-service ctl rebuildProjection Jobs --all --yes

Job node-data backfill

Job Service can repair missing node metadata in legacy jobs:

job-service ctl backfillNodeData (--all | --aggregate-id <id>) [flags]

It supports --dry-run, --yes, and --timeout (default 30 seconds). The command resolves historical pipeline information and applies corrections through ApplyJobCorrection.

Search migration

Run Search Service database migrations before starting it:

search-service migrate

The development Compose file runs this as a one-shot dependency of Search Service.

VHS process selection

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 task commands

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

mise tasks
mise run dev:chapter-inserter
mise run test:vhs-service
mise run lint:video-service

See Getting Started for setup.