CLI Reference

The complete command-line surface. This is the only CLI page in the wiki; the remaining pages document the WebUI.

Scope

Scheduled or scripted jobs: cron, a post-download hook, a CI step
Applying the same operation to many folders in a loop
Headless machines where you would rather not run a web server

What the CLI cannot do:

Create or edit metadata presets. It consumes a preset JSON; the editor is WebUI-only.
Bulk rename. WebUI-only.
Manual metadata edit. WebUI-only.
Manage encoding profiles or audio defaults. It uses them from appsettings.json, but they are created in the WebUI.

Both binaries share <data dir>/.remux-forge/appsettings.json, so profiles and settings you create in the WebUI are available to the CLI immediately.

General form

RemuxForge.Cli --mode remux|split|metadata [OPTIONS]

--mode is required. Run with no arguments, or with -h, to print the built-in help.

Exit codes: 0 success, 1 error.

Option names are case-insensitive and leading dashes are stripped, so -fs, --fs, -FS and --framesync are all the same thing.

RemuxForge.Cli --help

The built-in help is a concise overview. This page also documents audio source fill, aliases, validation rules and the complete value formats.

Common options

Valid in every mode.

Short	Long	Value	Description
	`--mode`	`remux`\|`split`\|`metadata`	Required
`-h`	`--help`, `-?`		Print help and exit
`-n`	`--dry-run`		Plan the work and print it, write nothing
`-r`	`--recursive`		Search subfolders
`-nr`	`--no-recursive`		Do not search subfolders
`-ext`	`--extensions`	list	Extensions to scan, comma-separated. Default `mkv`
	`--lang`	`en`\|`it`	Output language for this run

--extensions replaces the default rather than adding to it, and a leading dot is stripped, so --extensions .mkv,.mp4 and --extensions mkv,mp4 are equivalent.

Recursive search is on by default. Use -nr to turn it off.

Remux mode

Required

Short	Long	Value	Description
`-s`	`--source`	path	Folder with the source MKV files, or a single MKV file
`-t`	`--target-language`	codes	ISO 639-2 code(s) to import, e.g. `ita` or `eng,ita`

Plus an output: either -d or -o.

Language source

Short	Long	Value	Description
`-l`	`--language`	path	Folder to import tracks from, or a single MKV file. If omitted, the source folder is used, which gives a filter-only job

Output

Short	Long	Value	Description
`-d`	`--destination`	path	Output folder
`-o`	`--overwrite`		Overwrite the source files in place

-d and -o are mutually exclusive, and one of them is required.

Synchronization

Short	Long	Value	Description
`-fs`	`--framesync`		Visual frame comparison for a constant delay
`-da`	`--deep-analysis`		Full analysis for differently-edited releases. With imported audio, requires `--audio-format` and a scope of `lang` or `all`
	`--speed-correction`	`off`\|`manual`	Speed correction mode. Materialises the audio stretch with FFmpeg; with imported audio, requires `--audio-format` and a scope of `lang` or `all`
	`--no-speed-correction`		Equivalent to `--speed-correction off`
	`--stretch-factor`	factor	Manual factor, e.g. `25025/24000` or `1.001`. Implies `--speed-correction manual`
	`--analysis-crop-source-px`	`L:R:T:B`	Crop applied to source frames for matching only
	`--analysis-crop-lang-px`	`L:R:T:B`	Crop applied to language frames for matching only
	`--subtitle-canvas-rewrite`		Rewrite imported subtitle geometry. Requires `-fs` or `-da`
`-ad`	`--audio-delay`	ms	Manual audio offset, added to the automatic result
`-sd`	`--subtitle-delay`	ms	Manual subtitle offset
	`--framesync-diagnostics`		Dump frame-sync JSON to `.remux-forge/framesync-diagnostics/`
	`--deep-analysis-diagnostics`		Dump Deep analysis JSON to `.remux-forge/deepanalysis-diagnostics/`

-fs and -da are mutually exclusive. --speed-correction combines with either.

Accepted aliases: --analysis-crop-source, --analysis-crop-lang, --analysis-crop-language, --analysis-crop-language-px, --sub-canvas-rewrite. --speed-correction also accepts none/disabled for off.

Track filters

Short	Long	Value	Description
`-ac`	`--audio-codec`	codecs	Import only these audio codecs
`-so`	`--sub-only`		Import subtitles only
`-ao`	`--audio-only`		Import audio only
`-ksa`	`--keep-source-audio`	codes	Source audio languages to keep
`-ksac`	`--keep-source-audio-codec`	codecs	Source audio codecs to keep
`-kss`	`--keep-source-subs`	codes	Source subtitle languages to keep

-so and -ao are mutually exclusive. Omitting a keep option keeps everything, not nothing.

Matching

Short	Long	Value	Description
`-m`	`--match-pattern`	regex	Episode matching regex. Default `S(\d+)E(\d+)`

Audio processing

Long	Value	Description
`--audio-format`	`flac`\|`lpcm`\|`aac`\|`opus`\|`ac3`	Target format for processed tracks. Required for source fill, and for Speed correction or Deep analysis when Language audio is imported
`--audio-scope`	`disabled`\|`lang`\|`all`	`lang` processes every imported Language track, `all` extends the same processing to the final Source tracks
`--audio-24-to-16`		24-bit → 16-bit. FLAC/LPCM only
`--audio-peak-normalize`		Global multichannel peak normalization
`--audio-peak-target-db`	dB	Normalization target. Must be ≤ 0
`--audio-source-fill-threshold-ms`	ms	Minimum gap before source fill applies
`--audio-source-fill-language`	codes	Source audio language to take fill segments from
`--audio-source-fill-modes`	list	`start`, `end`, `insert-silence`, comma-separated

--audio-scope requires --audio-format. Audio source fill requires --audio-format, a scope of lang or all, a positive threshold, a language and at least one mode. insert-silence acts whenever the current EditMap contains Insert operations, produced by Deep analysis or applied manually in the Web editor.

Video encoding

Short	Long	Value	Description
`-ep`	`--encoding-profile`	name	Post-merge encoding profile, by name from `appsettings.json`

Tool paths

Short	Long	Value	Description
`-mkv`	`--mkvmerge-path`	path	Override the mkvmerge path for this run

Split mode

Required

Long	Value	Description
`-s`, `--source`	path	A single MKV file, or a folder for a batch

Plus exactly one cut mode.

Cut modes (choose exactly one)

Long	Value	Description
`--pattern`	`"5,5,5,6"`	Group chapters into segments. The sum must equal the chapter count
`--ranges`	`"T1-T2,T3-T4"`	Explicit ranges
`--split-at`	`"T1,T2"`	Cut points; produces N+1 segments
`--trim-start`	`T`	Drop everything before T
`--trim-end`	`T`	Drop everything after T
`--chapters-each`		One segment per chapter

--trim-start and --trim-end may be combined with each other. Everything else is exclusive: --pattern with --ranges is an error, and the shortcut modes (--split-at, --trim-*, --chapters-each) cannot be mixed with --pattern or --ranges. --split-at cannot be combined with either trim.

T accepts HH:MM:SS.mmm, MM:SS.mmm, decimal seconds, f<frame> for an exact frame index, or END.

Input and output

Long	Value	Description
`--source-raw`	file	Alternate PTS source. Single file only; must have the same frame count. Disables the fast path
`-d`, `--destination`, `-o`, `--output-dir`	path	Output folder. Empty = next to the input
`--output-template`	template	Output filename template
`--snap`	`off`\|`before`\|`after`\|`nearest`	Move segment starts to a keyframe. Anything other than `off` enables the fast path
`--force`		Overwrite existing outputs. Without it, existing segments are skipped
`--log`	path	Write a split log to this file

-o means different things in different modes. In split mode it is --output-dir and takes a path. In remux and metadata mode it is --overwrite and takes no value. Prefer the long forms in scripts.

Template tokens: {source_name}, {n}, {n:02d}, {n+213:03d}, {n-1}, {start}, {end}, {chapter_name}. Defaults: {source_name}.part{n:02d}.mkv for pattern/ranges/split-at, {source_name}_trimmed.mkv for trim, {source_name}.ch{n:02d}.mkv for chapters-each.

Metadata mode

Metadata mode processes .mkv only, and --extensions does not change that.

Long	Value	Description
`--preset`	path	Required. A preset JSON created by the WebUI preset editor
`-s`, `--source`	path	An `.mkv` file or a folder
`-d`, `--destination`, `--output-dir`	path	Write results to a separate folder
`-o`, `--overwrite`		Modify the source files in place
`--preserve-folder-structure`		Keep relative folders under the output directory
`--no-preserve-folder-structure`		Flatten everything into the output directory
`-r` / `-nr`		Recursion, as in every mode
`-n`, `--dry-run`		Analyze and report, write nothing

Unlike the WebUI, --preset takes an explicit path, so a preset does not have to live in .remux-forge/presets/metadata/. Presets created in the WebUI are there by default.

The preset contains only the rule pipeline. The output policy comes from these options, not from the preset.

Value formats

Kind	Format	Examples
Language codes	ISO 639-2, comma-separated	`ita`, `eng,ita`, `und`
Audio codecs	names or aliases, comma-separated	`E-AC-3`, `DTS,E-AC-3`, `DTS-HD MA`
Extensions	comma-separated, dot optional	`mkv`, `mkv,mp4`
Times	timecode, seconds, `f<frame>`, `END`	`00:21:40.500`, `21:40`, `1300.5`, `f31200`, `END`
Crop	`L:R:T:B` in pixels	`0:0:130:130`
Stretch	decimal or fraction	`1.001`, `25025/24000`
Delays	integer milliseconds, may be negative	`960`, `-1042`

Full language and codec tables, including the aliasing caveats, are in Codec and Language Reference.

Validation rules

Validation runs before any work starts and reports every problem at once.

Rule
`--mode` is required and must be `remux`, `split` or `metadata`
Remux: `--source` and `--target-language` are required
Remux: exactly one of `--destination` or `--overwrite`
Remux: `--framesync` and `--deep-analysis` are mutually exclusive
Remux: `--sub-only` and `--audio-only` are mutually exclusive
Remux: `--speed-correction manual` requires `--stretch-factor`
Remux: `--audio-scope` requires `--audio-format`
Remux: `--speed-correction` other than `off` requires `--audio-format` when Language audio is imported
Remux: `--deep-analysis` requires `--audio-format` when Language audio is imported
Remux: with speed correction or deep analysis the minimum `--audio-scope` is `lang`
Remux: `--audio-24-to-16` requires FLAC or LPCM
Remux: `--audio-peak-normalize` requires `--audio-format`, and the target must be ≤ 0 dB
Remux: audio source fill requires a format, a scope of `lang`/`all`, a positive threshold, a language and ≥ 1 mode
Remux: language codes must be valid ISO 639-2. A suggestion is offered for near misses
Remux: codec names must be known
Remux: `--match-pattern` must be a valid regex
Remux: in single-file mode `--source` and `--language` must both be files, and a filter-only job must leave `--language` empty
Remux: a selected file's extension must be allowed by `--extensions`
Remux: crop values must be `L:R:T:B` integers
Split: `--source` is required and must exist
Split: exactly one cut mode
Split: `--source-raw` must be a file, and single-file mode only
Split: `--pattern` sum must equal the chapter count
Metadata: `--preset` is required and must be a valid preset
At least one operation must actually be configured

Worked commands

Import an Italian dub with frame-sync:

RemuxForge.Cli --mode remux \
  -s "/media/Series.ENG" -l "/media/Series.ITA" \
  -t ita -d "/media/out" -fs

Deep analysis for a differently-edited release, with lossless audio rebuild:

RemuxForge.Cli --mode remux \
  -s "/media/EN" -l "/media/IT" -t ita -d "/media/out" \
  -da --audio-format flac --audio-scope lang

Deep analysis plus source fill:

RemuxForge.Cli --mode remux \
  -s "/media/EN" -l "/media/IT" -t ita -d "/media/out" \
  -da --audio-format flac --audio-scope lang \
  --audio-source-fill-threshold-ms 500 \
  --audio-source-fill-language eng \
  --audio-source-fill-modes start,end,insert-silence

Filter tracks with no import, overwriting in place:

RemuxForge.Cli --mode remux -s "/media/Series" -t ita -o \
  -ksa jpn,ita -kss ita

Split a disc into episodes with continued numbering:

RemuxForge.Cli --mode split \
  --source "/media/disc1.mkv" --pattern "5,5,5,6" \
  --output-dir "/media/out" \
  --output-template "Bleach.S12E{n+213:03d}.mkv" --snap nearest

Trim an intro, frame-perfect:

RemuxForge.Cli --mode split \
  --source "/media/rec.mkv" --trim-start "00:01:30" \
  --output-dir "/media/out" --snap off

Apply a metadata preset recursively, in place:

RemuxForge.Cli --mode metadata \
  --source "/media/Series" \
  --preset "/config/.remux-forge/presets/metadata/audio-titles.json" \
  --overwrite --recursive

Same, to a separate folder, preserving the folder tree:

RemuxForge.Cli --mode metadata \
  --source "/media/Series" \
  --preset "/config/presets/audio-titles.json" \
  --output-dir "/media/out" --preserve-folder-structure --recursive

Dry-run anything by adding -n:

RemuxForge.Cli --mode remux -s "/media/EN" -l "/media/IT" \
  -t ita -d "/media/out" -fs -n

Logging

Set REMUXFORGE_LOG_FILE to capture output to a file, which is normally required for scheduled runs:

REMUXFORGE_LOG_FILE=/var/log/remuxforge.log RemuxForge.Cli --mode remux ...

Split mode additionally has --log <path> for a split-specific log.

Uh oh!

CLI Reference

CLI Reference

Scope

General form

Common options

Remux mode

Required

Language source

Output

Synchronization

Track filters

Matching

Audio processing

Video encoding

Tool paths

Split mode

Required

Cut modes (choose exactly one)

Input and output

Metadata mode

Value formats

Validation rules

Worked commands

Logging

Next

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Start here

Using the WebUI

Examples

Reference

Clone this wiki locally