Reference

CLI reference

Every command the master and worker executables accept. These are operational commands — starting services, moving the database, recovering access.

Note

There is no submitcommand. Jobs are created through the web interface or by posting to the master's REST API. The CLI runs and maintains the services themselves.

On Windows the executables are master.exe and worker.exe. On macOS and Linux they are master and worker. Examples below use the POSIX form.

Master commands#

Run with no arguments, the master defaults to serve. Double-clicking the executable on Windows starts the service and opens the web console.

Command	What it does
`serve`	Run the service — REST API, web interface, worker channel. The default.
`migrate`	Bring the database schema up to date. The launcher runs this automatically on start.
`backup`	Take a consistent copy of the database while the service is running.
`restore`	Replace the live database with a backup file.
`seed`	Insert the default rows. Safe to run more than once.
`firstrun`	Open the setup dialog that writes `master.env`.
`firewall-install`	Add Windows Firewall rules for the master and worker. No effect on other platforms.
`reset-admin-password`	Set a new administrator password without touching job history.
`probe-v-deps`	Check that the EXR, colour and font tooling resolves. Exits non-zero if anything is missing.
`support-bundle`	Package one job's entire forensic trail into an archive to send to support.
`autostart`	Register or remove a per-user login entry so the master starts at sign-in.

serve#

start the master

$ master serve
$ master serve --open   # also open the web console in a browser

Prefer the launcher (start.bat / start.sh) for normal use. It loads master.env, puts the bundled FFmpeg on PATH, and runs migrations before starting the service. Calling serve directly skips all three.

backup and restore#

The backup is taken safely while the service is running. Do not copy the database file with a file manager instead — a live database captured mid-write is not reliably restorable.

backup and restore

$ master backup --out ./backups/2026-07-25.db
$ master restore --from ./backups/2026-07-25.db

Warning

restore overwrites the live database. Every job, worker registration and audit record created since that backup is lost. Stop the master first. The command asks for confirmation unless --yes is passed; that flag exists for scripted recovery and should be used deliberately.

restore accepts both a plain database file and a scheduled backup archive (a .zip). It verifies an archive against its manifest before replacing anything, keeps the database it replaced under a .pre-restorename, and refuses an archive taken by a newer version of the master than the one running. Scheduled backups, the archive format and the console's backup panels are covered on the Backups page.

reset-admin-password#

recover access

$ master reset-admin-password "a new password"

Reads the database location the same way serve does, so run it from the bundle folder. Pass --username to target an account other than the configured administrator.

seed#

default rows

$ master seed
$ master seed --demo   # also insert sample data

Important

--demo writes sample records into the database it is pointed at. It exists for screenshots and smoke tests. Do not run it against a master that holds real work.

probe-v-deps#

Checks that the image and colour tooling used by the EXR ingest paths resolves — the OpenImageIO tool, the LUT baker, and the ACES config. Prints what it found and exits non-zero if any are missing, which makes it usable as a deployment check.

preflight

$ master probe-v-deps

support-bundle#

Collects everything about one job — the job record, its chunks, the audit trail, the correctness report and the QC report — into a single archive.

package a job for support

$ master support-bundle --job q-7841 --out ./q-7841.tar.gz

Note

This is a command rather than an API route by design. If the master fails badly enough that the console does not load, the bundle can still be produced — the state in which it is most needed.

autostart#

start at login

$ master autostart enable
$ master autostart status
$ master autostart disable

Registers a per-user login entry and pins the executable's own directory as the working directory, so the environment file and database resolve the same way they do when the service is started manually.

Worker#

The worker runs the encode daemon. Normal operation takes no flags — it reads worker.env and the environment.

on each encoding machine

$ bash start.sh

It finds the master over the local network, registers, reports what it can encode, and waits for approval. See Add a worker for the full flow.

Diagnostic flags

Use these flags to inspect a worker's own state when it is not behaving as expected, before involving the master.

Flag	What it does
`--probe`	Print the capability manifest as JSON and exit — codecs, hardware encoders, GPUs and transport tier. This is the manifest the master receives at registration.
`--discover`	Browse the network for masters and list what it finds. Add `--discover-timeout` to wait longer.
`--test-encode`	Run a short synthetic encode benchmark on this machine.
`--probe-v-deps`	Check the worker's own image tooling. EXR chunks run the tooling on the worker, so successful resolution on the master does not verify this machine.
`--once`	Log a startup line and exit. Used as a smoke test.
`--firewall-install`	Add the Windows firewall rules, with an elevation prompt.
`--autostart`	`enable`, `disable` or `status` for a per-user login entry.
`--gui` / `--no-gui`	Force windowed or headless. The frozen worker runs a desktop interface by default.

Note

When a worker connects but does not receive the chunks you expect, run --probe first. If a codec is missing from the manifest, the scheduler is correct to skip the worker, and the problem is on that machine rather than in the fleet.

Version#

check the build

$ master --version

Check the version across the fleet. Master and workers should run the same release; a mismatched worker may report capabilities the master does not understand.