CLI

CLI

RemuxForge.Cli runs Remux, Split and Metadata jobs from a terminal. This page lists every command-line option, the WebUI startup arguments and the environment variables.

When to use it

• Scheduled or scripted jobs: cron, a post-download hook, a CI step.
• The same operation applied to many folders in a shell loop.
• Headless machines where a terminal is the natural interface.

The CLI runs the same processing engine as the WebUI and reads the same .remux-forge data directory, so everything configured in the WebUI is available to it: encoding profiles (-ep), audio encoder defaults, tool paths, advanced analysis settings and the interface language. Metadata presets built in the WebUI are plain JSON files that the CLI loads with --preset.

The data directory is shared when both programs resolve to the same location: extract the CLI and WebUI archives into the same folder, or point both at one folder with REMUXFORGE_DATA_DIR (see Environment variables).

Installation

Download the CLI archive for your platform from the releases page:

Platform	Archive
Windows x64	RemuxForge-Cli-win-x64.zip
Linux x64	RemuxForge-Cli-linux-x64.zip
Linux ARM64	RemuxForge-Cli-linux-arm64.zip
macOS x64 (Intel)	RemuxForge-Cli-osx-x64.zip
macOS ARM64 (Apple Silicon)	RemuxForge-Cli-osx-arm64.zip

SHA256SUMS on the same page lists the checksum of every archive.

Each archive contains a self-contained single-file executable, RemuxForge.Cli (RemuxForge.Cli.exe on Windows), so no .NET runtime is needed. The external tools (MKVToolNix, FFmpeg, MediaInfo) are the same ones the WebUI uses.

Linux and macOS:

unzip RemuxForge-Cli-linux-x64.zip
chmod +x RemuxForge.Cli
./RemuxForge.Cli --help

On macOS, clear the quarantine attribute once after extracting:

xattr -cr RemuxForge.Cli

Windows:

.\RemuxForge.Cli.exe --help

On first run the CLI creates .remux-forge next to the executable, or inside REMUXFORGE_DATA_DIR when that variable is set.

General form

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

• --mode is required and selects which option set is accepted. Its value is case-insensitive.
• Running with no arguments prints the built-in help. So does -h, --help or -? anywhere on the line, whatever else is present.
• Option names are case-insensitive and any number of leading dashes is accepted: -fs, --fs, -FS and --framesync are the same option.
• A value is always the next argument: --audio-format flac. Quote values that contain spaces.
• A value can start with - when the next character is a digit, so negative numbers such as -ad -1042 and --audio-gain-db -3.5 work.
• Options belong to their mode. An option from another mode is reported as Unknown parameter.

Common options

Valid in every mode.

Short	Long	Value	Default	Description
	--mode	remux, split, metadata		Operating mode. Required
-h	--help, -?			Print the help and exit
-n	--dry-run		Off	Plan the work and print it; output files stay untouched
-r	--recursive		On	Search subfolders of a source folder
-nr	--no-recursive			Search only the top level of a source folder
	--lang	en, it	See below	Language of console messages and help for this run

--lang also accepts eng, ita and regional forms such as en-US or it-IT. The language is chosen in this order: --lang, then the REMUXFORGE_LANG environment variable, then Ui.Language in appsettings.json, then English. Write it as --lang so the help and the earliest error messages use it as well.

Remux and Split read MKV, MP4, AVI and M2TS files: .mkv, .mp4, .m4v, .avi, .m2ts, .mts and .ts. The list is fixed. They always write MKV. Metadata mode reads .mkv files only.

Remux mode

Imports audio and subtitle tracks from a second release (the Language side) into the Source files, with optional synchronization, track filtering, audio processing and post-merge video encoding. The concepts are described in Remux synchronization.

Minimum command:

RemuxForge.Cli --mode remux -s <source> -t <languages> (-d <destination> | -o)

Input

Short	Long	Value	Default	Description
-s	--source	Path		Folder with the Source files, or a single file. Required
-l	--language	Path	Each file paired with itself	Folder with the files to import from, or a single file. When omitted with a Source folder, each Source file is paired with itself and the tracks are imported from the same file; a path equal to the Source folder counts as omitted
-t	--target-language	Codes		ISO 639-2 code(s) of the tracks to import, comma-separated: ita or eng,ita. Required
-m	--match-pattern	Regex	S(\d+)E(\d+)	Regular expression that extracts the episode ID from each file name. Source and Language files with the same ID are paired

Single-file mode: when -s is a file, -l must be a file too, and both must have one of the extensions above. The pair is processed directly, without pattern matching.

With two different folders, an episode found twice on one side (for example ep01.mp4 and ep01.mkv) is skipped, and so are files that would write the same output. The log names the files in conflict.

The files of a pair that are not MKV are remuxed together into temporary MKV files, in the temp folder, for the analyses that compare pictures and again for processing, and deleted after each step. With -n, processing remuxes only the Language file, and only when --copy-lang-chapters or Deep Analysis needs to read it; the printed command uses the original files.

Output

Short	Long	Value	Default	Description
-d	--destination	Path		Write the results to this folder, with the Source subfolders and names and the .mkv extension
-o	--overwrite		Off	Write each result next to its Source file as .mkv: an .mkv Source is replaced, a Source in another container is kept and the .mkv is written next to it

Exactly one of -d and -o is required.

Synchronization

Short	Long	Value	Default	Description
-fs	--framesync		Off	Measure one constant offset by visual frame comparison
-da	--deep-analysis		Off	Build an edit map for releases with different edits (cuts, inserts). With imported Language audio, requires --audio-format and a scope of lang or all
	--speed-correction	off, manual	off	Speed correction mode. none and disabled are accepted for off. manual requires --stretch-factor
	--stretch-factor	Factor		Stretch factor applied to the Language timeline: any positive decimal or fraction, for example 1001/960, 25025/24000, 1.0427. Sets --speed-correction manual
	--no-speed-correction			Same as --speed-correction off; clears a factor given earlier on the line
	--analysis-crop-source-px	L:R:T:B	None	Pixels cropped from the Source frames for visual matching only. Aliases: --analysis-crop-source
	--analysis-crop-lang-px	L:R:T:B	None	Pixels cropped from the Language frames for visual matching only. Aliases: --analysis-crop-lang, --analysis-crop-language, --analysis-crop-language-px
-ad	--audio-delay	ms	0	Manual audio offset in integer milliseconds, added to the automatic result
-sd	--subtitle-delay	ms	0	Manual subtitle offset in integer milliseconds, added to the automatic result

• -fs and -da are mutually exclusive. Speed correction combines with either.
• Speed correction renders the imported Language audio with FFmpeg, so with imported Language audio it requires --audio-format and a scope of lang or all. It verifies the given factor visually and resolves the constant offset.
• Among --speed-correction, --stretch-factor and --no-speed-correction, the last one on the line decides the mode.
• The UI offers twelve standard conversions (see Remux synchronization); the CLI takes any positive factor, which covers non-standard transfers.
• A crop of 0:0:0:0 is the same as no crop.
• -fs and -da work only on progressive video and need MediaInfo. An episode whose Source or Language video is interlaced (Interlaced, MBAFF, PAFF or Mixed in MediaInfo), or whose scan type MediaInfo cannot read, ends in error with the reason. Without -fs and -da the video is copied as it is.

Track filters

Short	Long	Value	Default	Description
-ac	--audio-codec	Codecs	All	Import only Language audio tracks with these codecs, comma-separated
-so	--sub-only		Off	Import subtitles only
-ao	--audio-only		Off	Import audio only
-ksa	--keep-source-audio	Codes	All	Source audio languages to keep, comma-separated
-ksac	--keep-source-audio-codec	Codecs	All	Source audio codecs to keep, comma-separated
-kss	--keep-source-subs	Codes	All	Source subtitle languages to keep, comma-separated

-so and -ao are mutually exclusive. A keep option that is absent keeps every Source track of that kind. Codec names and aliases (E-AC-3, DD+, DTS-HD MA, TrueHD, FLAC and more) are listed in Codec and language reference.

Subtitles and chapters

Short	Long	Value	Default	Description
	--subtitle-canvas-rewrite		Off	Rewrite the geometry of imported PGS, ASS/SSA and VobSub subtitles to the Source canvas. Alias: --sub-canvas-rewrite
	--copy-lang-chapters		Off	Replace the Source chapters with the Language file's chapters, retimed with the same transformation as the imported subtitles (Deep Analysis edit map, stretch, subtitle delay)

• Canvas rewrite uses the geometry measured by FrameSync or Deep Analysis, so it takes effect together with -fs or -da. Without that geometry the log reports that the rewrite was skipped and the subtitles are muxed unchanged.
• With --copy-lang-chapters, a Language file without chapters produces an output without chapters. The log reports how many chapters were copied, moved to a cut junction or dropped.

Audio processing

Short	Long	Value	Default	Description
	--audio-format	flac, lpcm, aac, opus, ac3	None	Target format of processed tracks
	--audio-scope	disabled, lang, all	disabled, or all once a format is set	lang processes every imported Language track; all also processes the Source tracks kept in the output. Accepted aliases: off/no for disabled, language for lang
	--audio-24-to-16		Off	Convert 24-bit audio to 16-bit with dither. FLAC and LPCM only
	--audio-peak-normalize		Off	Global multichannel peak normalization
	--audio-peak-target-db	dB	-1.0	Normalization target, from -60 to 0
	--audio-gain-db	dB		Fixed gain applied to every processed track, from -12 to +12, decimals allowed

• --audio-format without --audio-scope sets the scope to all. Give --audio-scope lang to limit processing to the imported tracks.
• --audio-scope other than disabled requires --audio-format.
• Normalization, fixed gain and 24-to-16 require a format and an active scope.
• --audio-peak-normalize and --audio-gain-db are mutually exclusive.
• Encoder settings, such as the FLAC compression level, come from Settings ▸ Audio in the WebUI. See Settings.

Audio source fill

Fills gaps in the imported audio with Source audio: before the imported track starts, after it ends, and at the Insert operations of the edit map.

Short	Long	Value	Default	Description
	--audio-source-fill-threshold-ms	ms	0	Minimum gap, in integer milliseconds, that is filled
	--audio-source-fill-language	Code		Source audio language used as fill, one ISO 639-2 code
	--audio-source-fill-modes	List		start, end, insert-silence, comma-separated
	--audio-source-fill-gain-db	dB	0	Gain applied to the Source audio used as fill, from -12 to +12, decimals allowed

Source fill is active as soon as any of the four options is given. It then requires --audio-format, an active scope, a threshold greater than zero, a language and at least one mode. insert-silence fills the Insert operations of the edit map produced by Deep Analysis. The fill gain is written into the filled Insert operations and also applies to the start and end fill.

Video encoding

Short	Long	Value	Default	Description
-ep	--encoding-profile	Name	None	Re-encode the merged video with this encoding profile. The name matches a profile in appsettings.json exactly, case included

Profiles are created in the WebUI under Settings ▸ Encoding profiles. A name that matches no profile produces a warning and the files are written without re-encoding.

Tool paths

Short	Long	Value	Default	Description
-mkv	--mkvmerge-path	Path	Tools.MkvMergePath from settings, else mkvmerge	mkvmerge executable for this run

When the given path is not a working mkvmerge executable, RemuxForge resolves mkvmerge automatically, as it does at startup. FFmpeg, ffprobe, mkvextract, mkvpropedit and MediaInfo paths come from appsettings.json.

Diagnostics

Short	Long	Value	Default	Description
	--framesync-diagnostics		Off	Write the FrameSync analysis of every episode as JSON and CSV
	--deep-analysis-diagnostics		Off	Write the Deep Analysis result of every episode as JSON

Details in Diagnostics.

Split mode

Cuts MKV, MP4, AVI and M2TS files into MKV segments or episodes, by chapters or by time.

Minimum command:

RemuxForge.Cli --mode split -s <file-or-folder> <one cut mode>

Input and output

Short	Long	Value	Default	Description
-s	--source	Path		A single video file, or a folder for a batch. Required
-d, -o	--destination, --output-dir	Path	Next to each input file	Output folder, created when missing
	--output-template	Template	Per cut mode	Output file name without extension; see Output template
	--start-number	Integer	1	Number assigned to the first {episode}
	--snap	off, before, after, nearest	nearest	Move each cut to a keyframe
	--split-quality	Integer	Per codec	Quality of the frames re-encoded by --snap off: CRF or q, depending on the codec. Requires --snap off
	--split-speed	Value	Per codec	Encoder speed of the frames re-encoded by --snap off: preset or cpu-used, depending on the codec. Requires --snap off
	--force		Off	Overwrite outputs that already exist

• With a folder, every supported file is processed, recursively unless -nr is given, in name order. The cut options apply to every file. All the files must have the same video codec and the same scan type, progressive or interlaced: otherwise the batch stops before any work with Batch processing REQUIRES the same video codec and the same scan type in all files. A file that fails is reported and the batch continues with the next one.
• With an output folder and a source folder, the subfolders of the source are recreated inside the output folder.
• The outputs of a file are independent: when one fails, the others are still written, and the log lists the failed ones at the end.
• Each output is written in a hidden .remuxforge-split-… folder next to its destination and renamed into place when complete. Keep free space there for at least twice the largest output, plus, for a source that is not MKV, one temporary MKV copy in the temp folder.
• An output that already exists is skipped with SKIP: ... already exists, which lets an interrupted batch resume. --force overwrites it.
• -o in Split mode is the output folder and takes a path. In Remux and Metadata mode -o is --overwrite and takes no value. Long forms read unambiguously in scripts.

Cut modes

Choose exactly one.

Long	Value	Description
--pattern	5,5,5,6	Group consecutive chapters into episodes. The sum must equal the file's chapter count
--chapters-per-episode	k	Group chapters into blocks of k. Adapts to any chapter count; when the count is not a multiple of k, the last episode is shorter and a warning says so
--chapters-each		One segment per chapter
--ranges	T1-T2,T3-T4	Explicit ranges. A single range behaves as a trim
--split-at	T1,T2	Cut points; N points produce N+1 contiguous segments
--trim-start	T	Keep everything from T
--trim-end	T	Keep everything up to T

• --trim-start and --trim-end combine with each other into one segment.
• --pattern and --ranges are mutually exclusive, and neither combines with the shortcut modes (--split-at, --trim-*, --chapters-each, --chapters-per-episode).
• --split-at and --chapters-each each stand alone.
• Chapter-based modes require the file to have chapters.
• Time values are described in Value formats. Ranges past the end of the file are clamped with a warning.

Snap and processing path

--snap	Cut lands on
nearest	The closest keyframe
before	The previous keyframe
after	The next keyframe
off	The exact requested frame

A segment that starts and ends on keyframes (or at the end of the file) is copied with mkvmerge, for any video codec. With a snap mode, MediaInfo must report the frame rate mode of the main video track. --snap off cuts on the exact frame: a boundary that already falls on a keyframe is copied, the others re-encode the frames next to the cut and copy the rest. Exact cutting depends on the video:

Video	--snap off	--split-quality: scale, range, default	--split-speed: setting, values, default
H.264, H.265 (HEVC)	Yes	CRF, 0-51, 14	preset, ultrafast to placebo, medium
AV1	Yes	CRF, 0-63, 16	preset, 0-13, 6
VP9	Yes	CRF, 0-63, 15	cpu-used, 0-8, 2
MPEG-2, Xvid/DivX (MPEG-4 ASP), DivX 3, MS-MPEG4v2, H.263	Yes	q, 1-31, 2	none: --split-speed is an error
VC-1, any other codec	No: keyframes only
Interlaced video, any codec	No: keyframes only

A cut that --snap off cannot honor makes the plan invalid, with the reason. On interlaced video a cut can fall on an open-GOP keyframe; it is accepted with a warning that says whether frames are lost or the boundary moves back. Details in Split wizard and Internals.

Output template

The template is the output file name without extension; .mkv is appended automatically.

Variable	Value
{source}	Input file name without extension. When the same folder holds another supported file with the same name, the .mkv keeps the plain name and the others keep their extension: film.part01.mkv, film.avi.part01.mkv
{n}	Segment number, from 1
{episode}	--start-number + segment number - 1
{chapter}	Name of the segment's first chapter
{start}	Segment start, as HHhMMmSSs
{end}	Segment end, as HHhMMmSSs
{duration}	Segment duration, as HHhMMmSSs

• :02 pads a number to two digits: {n:02}, {episode:02}. It is the only format specifier.
• / or \ in the template creates subfolders under the output folder. The template is a relative path: an absolute path or .. is rejected.
• Characters that are invalid in file names are replaced with _, and trailing spaces and dots are removed from each path component.
• The template is validated before any work starts. Older templates are reported with their replacement: {source_name} becomes {source}, {chapter_name} becomes {chapter}, and {n+K} becomes {episode} together with --start-number.

Defaults:

Cut mode	Default template	Example output
--pattern, --chapters-per-episode	{source}.E{episode:02}	disc1.E01.mkv
--chapters-each	{source}.ch{n:02}	concert.ch01.mkv
--ranges (two or more), --split-at	{source}.part{n:02}	disc1.part01.mkv
--trim-start, --trim-end, single range	{source}_trimmed	rec_trimmed.mkv

Dry run

-n analyses each file, prints the chapter count, the frame count and the complete plan (segments, boundaries, output names, processing path), and ends with (dry run).

Metadata mode

Applies a metadata preset to .mkv files: track names, languages, flags, tags and the other rules a preset can contain.

Minimum command:

RemuxForge.Cli --mode metadata -s <file-or-folder> --preset <preset.json>

Short	Long	Value	Default	Description
-s	--source	Path		An .mkv file, or a folder. A single file in another container is refused; in a folder, video files that are not .mkv are skipped and counted in the log. Required
	--preset	Path		Metadata preset JSON file. Required
-d	--destination, --output-dir	Path		Write the results to this folder and leave the inputs untouched
-o	--overwrite		In place	Modify the input files in place
	--overwrite-output		Off	Replace files that already exist in the output folder
	--preserve-folder-structure		On	Recreate the relative subfolders of the source under the output folder
	--no-preserve-folder-structure			Write every result directly into the output folder

• Without -d, files are modified in place; -o states that explicitly. When both -d and -o are given, the later one on the line decides.
• --preset takes a file path, absolute or relative to the current directory. Presets created in the WebUI are stored in <data dir>/.remux-forge/presets/metadata/ as .json files, so a WebUI preset is addressed by its path there. See Metadata presets.
• The preset holds the rules; the output policy comes from the options above.
• With an output folder, a result whose file already exists is skipped with skipped: Metadata output already exists unless --overwrite-output is given. Two inputs that would produce the same output file (possible with --no-preserve-folder-structure) are skipped as a collision. The rest of the batch continues.
• Recursion follows -r/-nr, on by default.
• -n analyses every file against the preset and writes nothing.
• Tool paths for mkvmerge, mkvpropedit, mkvextract and MediaInfo come from appsettings.json.

Diagnostics output

Both diagnostics flags write into the data directory, one set of files per episode, named after the episode ID and a timestamp (<episode>-yyyyMMdd-HHmmssfff).

Flag	Folder	Files
--framesync-diagnostics	<data dir>/.remux-forge/framesync-diagnostics/	<name>.json with the full result, plus <name>-candidates.csv, <name>-points.csv, <name>-geometry.csv
--deep-analysis-diagnostics	<data dir>/.remux-forge/deepanalysis-diagnostics/	<name>.json with the result and the analysis settings in effect

• FrameSync diagnostics are written for every episode that has a FrameSync result, and accumulate across runs.
• The Deep Analysis folder holds the diagnostics of the latest run: it is emptied at the start of every Remux scan. Deep Analysis diagnostics are also written when Advanced.DeepAnalysis.DiagnosticsEnabled is true in appsettings.json.
• The console log prints the path of each file written.

WebUI startup arguments

The WebUI executable, RemuxForge.Web, takes one startup argument:

Argument	Value	Default	Description
--port	1-65535	5000	HTTP port. Spelled exactly --port

./RemuxForge.Web --port 5050

The WebUI listens on all network interfaces. When REMUXFORGE_PORT is set, it decides the port and --port is ignored. A value outside 1-65535 falls back to 5000.

Environment variables

Variable	Used by	Default	Description
REMUXFORGE_DATA_DIR	CLI, WebUI	Executable directory	Parent directory of .remux-forge, which holds settings, presets and temporary files
REMUXFORGE_PORT	WebUI	5000	HTTP port; takes precedence over --port
REMUXFORGE_LOG_FILE	CLI, WebUI	Disabled	Append log lines to this file
REMUXFORGE_LANG	CLI, WebUI	Ui.Language, else en	Interface, log and console language at start-up, en or it, in place of the saved one. --lang takes precedence in the CLI

REMUXFORGE_DATA_DIR=/srv/remuxforge ./RemuxForge.Cli --mode remux ...

Value formats

Kind	Format	Examples
Language codes	ISO 639-2, comma-separated where a list is accepted	ita, eng,ita, jpn, und
Audio codecs	Names or aliases, comma-separated, case-insensitive	E-AC-3, DD+, DTS,E-AC-3, "DTS-HD MA"
Delays, thresholds	Integer milliseconds, negative allowed for delays	960, -1042
Gains, dB targets	Decimal with . as separator	-1, -3.5, 2.25
Stretch factor	Positive decimal or fraction a/b	1.0427, 1001/960, 25/23.976
Crop	L:R:T:B, integers ≥ 0, in pixels	0:0:130:130
Episode pattern	.NET regular expression	S(\d+)E(\d+), [Ee]p(?:isode)?[ ._-]?(\d+)
Split times	HH:MM:SS.mmm, MM:SS.mmm, decimal seconds, f<frame>, END	00:21:40.500, 21:40, 1300.5, f31200, END
Split pattern	Chapter counts, comma-separated	5,5,5,6

• END is written in upper case and means the end of the file.
• f<frame> (or F<frame>) is a zero-based frame index, resolved against the file's real timestamps, so it is exact on VFR content.
• Split times use . as the decimal separator.
• Language codes are checked against the ISO 639 list; a near miss gets a Did you mean suggestion. Full tables in Codec and language reference.

Validation rules

Parsing reads the line left to right and stops at the first malformed option. Validation then runs before any work starts and reports every remaining problem at once, each line prefixed with Error:. Checks that need the files themselves, such as the pattern sum in Split, run when each file is analyzed.

Parsing

Rule	Message
--mode is present and is remux, split or metadata	Missing required parameter: --mode remux|split|metadata, Invalid mode: ...
Every option exists in the selected mode	Unknown parameter: -<name>
An option that takes a value is followed by one	Missing value for -<name>
--lang is en or it	Invalid language: ...
Delays, threshold and dB values are numbers	Invalid value for <option>: ...
--speed-correction is off or manual	Invalid speed-correction mode: ...
--audio-format is flac, lpcm, aac, opus or ac3	Invalid audio format: ...
--audio-scope is disabled, lang or all	Invalid audio scope: ...
--audio-source-fill-modes contains only start, end, insert-silence	Invalid audio-source-fill mode: ...
--snap is off, before, after or nearest	--snap must be one of: off, before, after, nearest
--split-quality is an integer	--split-quality must be an integer

Remux

Rule
--source and --target-language are required
Exactly one of --destination and --overwrite
--framesync and --deep-analysis are mutually exclusive
--sub-only and --audio-only are mutually exclusive
--speed-correction manual requires a valid --stretch-factor (positive decimal or fraction)
--audio-scope other than disabled requires --audio-format
Speed correction and Deep Analysis with imported Language audio require --audio-format and a scope of lang or all
--audio-24-to-16 is for flac and lpcm
Normalization, fixed gain and 24-to-16 require a format and an active scope
--audio-peak-target-db is between -60 and 0
--audio-gain-db is between -12 and +12, and excludes --audio-peak-normalize
Audio source fill requires a format, an active scope, a threshold > 0, a language and at least one mode
--audio-source-fill-gain-db is between -12 and +12
Language codes in -t, -ksa, -kss and the fill language are valid ISO 639 codes
Codec names in -ac and -ksac are known
--match-pattern is a valid regular expression
In single-file mode --source and --language are both files with a supported extension
The source and language folders exist
mkvmerge is available

Split

Rule
--source is required and exists
Exactly one cut mode
The output template is relative, has closed braces, uses known variables and only the :02 format
--pattern sums to the chapter count
Chapter-based modes need a file with chapters
--split-at points are unique and inside the file
--split-quality and --split-speed require --snap off, and must be in the range of the codec
With a folder, all files have the same video codec and the same scan type
With --snap off, cuts off a keyframe need a codec with exact cutting and progressive video
With a snap mode, MediaInfo reports the frame rate mode

Metadata

Rule
--source and --preset are required
A single --source file is an .mkv
The preset loads and passes preset validation

Recipes

Paths are examples; the commands use Linux syntax. On Windows use RemuxForge.Cli.exe and replace the trailing \ with ` in PowerShell, or write each command on one line.

Remux

Import an Italian dub, already in sync:

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

Import subtitles only:

RemuxForge.Cli --mode remux -s "/media/Series" -l "/media/Series.SUBS" -t ita -d "/media/out" -so

Constant offset, measured by FrameSync:

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

PAL to film speed difference (Source 23.976, Language 25):

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

Free stretch factor for a non-standard transfer (CLI only; any positive decimal or fraction):

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

Different edits, with Deep Analysis:

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

Deep Analysis with Source fill for a missing opening and removed scenes:

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,insert-silence

Keep chosen Source tracks only:

RemuxForge.Cli --mode remux -s "/media/Source" -l "/media/IT" -t ita -d "/media/out" \
  -ksa jpn -kss ita,eng

Import only the lossless track:

RemuxForge.Cli --mode remux -s "/media/Source" -l "/media/IT" -t ita -d "/media/out" \
  -ac "DTS-HD MA"

Fix subtitle placement between 720p and 1080p releases:

RemuxForge.Cli --mode remux -s "/media/1080p" -l "/media/720p" -t ita -d "/media/out" \
  -fs --subtitle-canvas-rewrite

Take the chapters from the Language release:

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

Non-standard episode numbering:

RemuxForge.Cli --mode remux -s "/media/EN" -l "/media/IT" -t ita -d "/media/out" \
  -m "[Ee]p(?:isode)?[ ._-]?(\d+)"

Convert the imported dub to 16-bit FLAC:

RemuxForge.Cli --mode remux -s "/media/Source" -l "/media/IT" -t ita -d "/media/out" \
  --audio-format flac --audio-scope lang --audio-24-to-16

Lower the imported dub by 3 dB:

RemuxForge.Cli --mode remux -s "/media/Source" -l "/media/IT" -t ita -d "/media/out" \
  --audio-format flac --audio-scope lang --audio-gain-db -3

Re-encode the video after merging (profile created in the WebUI):

RemuxForge.Cli --mode remux -s "/media/EN" -l "/media/IT" -t ita -d "/media/out" \
  -ep hevc-slow-crf22

Overwrite the Source files in place:

RemuxForge.Cli --mode remux -s "/media/Series" -l "/media/IT" -t ita -o

Single pair of files:

RemuxForge.Cli --mode remux -s "/media/EN/Movie.mkv" -l "/media/IT/Film.mkv" -t ita -d "/media/out" -fs

Dry run before committing a season:

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

Collect diagnostics for a bad sync result:

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

Attach the JSON from .remux-forge/deepanalysis-diagnostics/ to the bug report. For FrameSync, use -fs --framesync-diagnostics and attach the files from .remux-forge/framesync-diagnostics/.

Split

A disc rip into four episodes by chapter groups:

RemuxForge.Cli --mode split --source "/media/disc1.mkv" --pattern "5,5,5,6" \
  --output-dir "/media/out"

Output: disc1.E01.mkv to disc1.E04.mkv.

Fixed number of chapters per episode:

RemuxForge.Cli --mode split --source "/media/disc1.mkv" --chapters-per-episode 5 \
  --output-dir "/media/out"

Continue an existing season numbering (episodes 214 to 217):

RemuxForge.Cli --mode split --source "/media/disc1.mkv" --pattern "5,5,5,6" \
  --output-dir "/media/out" --output-template "Bleach.S12E{episode}" --start-number 214

Output: Bleach.S12E214.mkv to Bleach.S12E217.mkv, ready for the default Remux pattern S(\d+)E(\d+).

Explicit ranges ending at the end of the file:

RemuxForge.Cli --mode split --source "/media/disc1.mkv" \
  --ranges "00:00:00-00:21:40,00:21:40-END" --output-dir "/media/out"

Split at a point:

RemuxForge.Cli --mode split --source "/media/rec.mkv" --split-at "21:40" --output-dir "/media/out"

Trim an intro and an outro, frame-exact:

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

Cut on exact frames:

RemuxForge.Cli --mode split --source "/media/disc1.mkv" \
  --ranges "f0-f31200,f31200-END" --snap off --output-dir "/media/out"

One file per chapter, named after the chapter:

RemuxForge.Cli --mode split --source "/media/concert.mkv" --chapters-each \
  --output-dir "/media/out" --output-template "{source}.ch{n:02} - {chapter}"

Batch a folder of discs with the same structure, one subfolder per disc:

RemuxForge.Cli --mode split --source "/media/boxset" --pattern "5,5,5,6" \
  --output-dir "/media/out" --output-template "{source}/{source}.E{episode:02}"

Dry run, to read the chapter count and the planned names:

RemuxForge.Cli --mode split --source "/media/disc1.mkv" --pattern "5,5,5,6" \
  --output-dir "/media/out" -n

Run again over existing outputs:

RemuxForge.Cli --mode split --source "/media/disc1.mkv" --pattern "5,5,5,6" \
  --output-dir "/media/out" --force

Metadata

Apply a WebUI preset recursively, in place:

RemuxForge.Cli --mode metadata --source "/media/Series" \
  --preset "/opt/remuxforge/.remux-forge/presets/metadata/audio-titles.json"

Write to a separate folder, keeping the folder tree:

RemuxForge.Cli --mode metadata --source "/media/Series" \
  --preset "./audio-titles.json" --output-dir "/media/out"

Flatten into one folder and replace earlier results:

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

Preview the changes:

RemuxForge.Cli --mode metadata --source "/media/Series" --preset "./audio-titles.json" -n

Scripting

Loop over several series folders:

for dir in /media/EN/*/; do
  name=$(basename "$dir")
  RemuxForge.Cli --mode remux -s "$dir" -l "/media/IT/$name" -t ita -d "/media/out/$name" -fs
done

Scheduled run with a log file:

REMUXFORGE_LOG_FILE=/var/log/remuxforge.log \
  /opt/remuxforge/RemuxForge.Cli --mode split --source "/media/incoming" \
  --chapters-per-episode 6 --output-dir "/media/episodes"

Logging and exit codes

Console output

Messages go to the console in color. Remux mode prints a banner, the effective configuration, the per-episode analysis and merge log, a detailed report (Source, Language and result tables with delay, FrameSync, Deep, speed and merge columns) and a summary with the counts of processed, skipped, unmatched, track-less, sync-failed and failed files. Split prints the plan of each file and the progress of each segment. Metadata prints one line per file.

Log file

Set REMUXFORGE_LOG_FILE to append log lines to a file, one per message:

2026-10-07 21:14:03 [SECTION] [LEVEL] message

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

In Remux mode the file is emptied at the start of each scan, so it holds the log of the latest run. Split and Metadata append to it.

Exit codes

Code	Meaning
0	Help printed; the job completed; a dry run completed
1	Invalid arguments or validation failure
1	Remux: initialization failed (missing mkvmerge, missing folder, required tool unavailable)
1	Split: no input files, or at least one file failed
1	Metadata: the preset failed to load or validate, or at least one file failed

In Remux mode, once initialization succeeds the exit code is 0 and the outcome of each episode is reported in the summary (Processed, Skipped, No match, No tracks, Sync failed, Errors). A script that needs per-episode results reads the summary or the log file. In Metadata mode, files skipped for an existing output or a collision are reported as warnings.

Next

• Home
• Troubleshooting
• Settings
• Codec and language reference