Commands

subtrace scan       walk the libraries, record what is missing (no network)
subtrace fetch      scan, then download subtitles for pending items
subtrace watch      fetch on a loop — the container's default command
subtrace status     counts, quota used today, recent failures (read-only)
subtrace config     init | show | validate

Global flags

Available on every command:

Flag	Default	Effect
`--config`, `-c`	resolution order	Path to `subtrace.toml`.
`--dry-run`	`false`	Do everything except write subtitle files. Also skips the writability probe.
`--log-level`	`info`	`debug`, `info`, `warn`, `error`. Logs go to stderr.
`--version`	—	Print the build version.

`scan`

Walks every configured root, records what it finds, prints a summary. Never touches the network, so it works before any provider credentials exist.

Flag	Default	Effect
`--sample`	`10`	How many missing files to list afterwards (`0` for none).

Beyond reporting, a scan keeps the database honest: files that have gained a sidecar are marked have, and rows for files that no longer exist on disk are pruned (pruned (gone from disk) in the output).

`fetch`

Scans, then works through pending items, trying each provider in order until one delivers. Before any work it probes every library root for writability, so a permissions problem surfaces immediately instead of thousands of files in.

Flag	Default	Effect
`--limit`	`run.max_per_run`	Cap subtitles fetched this run.
`--kind`	all	`movie` or `tv`.
`--lang`	all	A single language code.
`--path`	all	Only files under this path prefix.
`--force`	`false`	Retry items previously marked `not_found` or `failed`, ignoring backoff and `max_attempts`.
`--skip-scan`	`false`	Use the existing database instead of re-walking the library.

subtrace fetch --limit 10
subtrace fetch --kind tv --lang es
subtrace fetch --path "/media/TV Shows/1923 {tmdb-157744}" --force
subtrace fetch --dry-run --log-level debug

--skip-scan is worth knowing about on a large or network-mounted library: the walk is the slow part, and after the first run of the day the database already knows what is pending.

`watch`

Runs a fetch immediately, then repeats on an interval. This is the container’s default command. It shuts down cleanly on SIGTERM — an in-flight fetch is cancelled between items, never mid-write.

Flag	Default	Effect
`--interval`	`run.interval`	Override the loop interval, e.g. `6h`.
`--limit`	`run.max_per_run`	Cap each run.
`--kind`	all	`movie` or `tv`.
`--lang`	all	A single language code.

`status`

Reads the database only — safe to run while a fetch is in progress.

Flag	Default	Effect
`--quiet`, `-q`	`false`	Print nothing; exit non-zero if the state is unreadable. Used as the container healthcheck.
`--limit`, `-n`	`5`	How many failed / not-found items to list (`0` for all).

config                     /config/subtrace.toml
database                   /config/subtrace.db
providers                  [opensubtitles subdl]
languages                  [en]

tracked (file × language)  8412
  have                     6011
  downloaded               812
  pending                  1503
  not_found                74
  failed                   12

files by kind
  movie                    1204
  tv                       7208

downloads today
  opensubtitles            100 / 100
  subdl                    37 / 100

recent failures
  /media/Movies/... [en] attempt 2 at 2026-07-24T09:11:04-07:00
    not a valid subtitle file: provider returned an HTML page

What the statuses mean is on How it works.

`config`

Subcommand	What it does
`config init`	Print a fully commented starter config to stdout. Redirect it to a file.
`config show`	Print the effective config — after env overrides and fallbacks — with secrets masked.
`config validate`	Parse and check the config. No network.

subtrace config init > subtrace.toml
subtrace config validate
subtrace config show

config show is the right thing to attach to a bug report: it is the real configuration, and secrets are already masked.

Naming and matching Providers