CLI Reference

The freemkv binary has two forms:

# Rip / remux: a source and a destination. No command word — the action is
# implied by passing two URLs.
freemkv <source> <destination> [flags]

# Subcommand: the first argument is the command.
freemkv <subcommand> [args]              # info, verify, update-keys, version, help

A bare invocation prints usage and exits 2.

Stream URLs

Every source and destination is a scheme:// URL.

URL	Source	Dest	Notes
`disc://`	✓	—	Optical drive (auto-detected; `disc:///dev/sg4` or `disc://D:` to target one)
`iso://path.iso`	✓	✓	Disc image
`mkv://path.mkv`	✓	✓	Matroska movie
`m2ts://path.m2ts`	✓	✓	Blu-ray transport stream
`network://host:port`	✓	✓	TCP (listen or connect)
`stdio://`	✓	✓	Stdin / stdout
`null://`	—	✓	Discard (read-speed benchmark)
`dir://path/`	—	✓	Planned — decrypted file tree (VIDEO_TS / BDMV)

disk:// is an alias for disc://. Everything is decrypted by default; --raw (iso:// only) is the sole encrypted output. BD/UHD discs need an AACS key — see Decryption Keys; DVDs need none.

Scheme details

What each scheme does, and when to reach for it.

disc://

Rips the main title by default. Pick others with -t N, or several at once:

freemkv disc:// mkv://Movie.mkv          # main title → one file
freemkv disc:// -t 1 -t 3 mkv://out/     # titles 1 and 3 → out/ (a directory)

iso://

As a source (iso://Movie.iso), it rips all titles by default — so the output has to be a directory, because multiple titles means multiple files:

freemkv iso://Movie.iso mkv://out/             # every title → out/Movie_t1.mkv, out/Movie_t2.mkv, …
freemkv iso://Movie.iso -t 1 mkv://Movie.mkv   # just title 1 → a single file

As a destination (iso://Movie.iso), it writes a decrypted sector image of the disc:

freemkv disc:// iso://Movie.iso          # rip the disc to a decrypted image

…plus two flags that work only with iso://:

--multipass — sweep, then retry the bad sectors, with a resumable mapfile sidecar (sector state only — never keys). Re-run until clean. Damaged-disc workflow: disc:// iso:// --multipass, then iso:// mkv://.
--raw — write the sectors encrypted, a faithful image. You can’t mux or benchmark ciphertext, so both flags error on any other destination.

A plain disc:// iso:// auto-resumes if interrupted.

mkv://

Writes one decrypted movie. A single title goes to the file you name; multiple titles go to a directory, one file each, named <disc>_t<N>.mkv:

freemkv disc:// mkv://Movie.mkv          # single title → Movie.mkv
freemkv disc:// -t 1 -t 3 mkv://out/     # → out/Greenland_t1.mkv, out/Greenland_t3.mkv

m2ts://

Same as mkv://, but writes a Blu-ray transport stream — one file for a single title, or <disc>_t<N>.m2ts per title into a directory.

stdio://

Writes the muxed output to stdout (or reads it from stdin), so you can chain freemkv into a pipe with no intermediate file. The classic use is transcoding on the fly with ffmpeg:

freemkv disc:// stdio:// | ffmpeg -i - -c:v libx265 Movie.mkv

network://host:port

Streams a rip over TCP instead of to a file: one end listens (network://0.0.0.0:9000), the other connects (network://192.0.2.10:9000). Rip on the machine with the drive and mux or store on another — no shared filesystem needed.

null://

Reads and discards everything — a read-speed benchmark or dry run, with no output written.

dir:// (planned)

Extracts the decrypted on-disc file tree (VIDEO_TS/ or BDMV/) straight into the folder. Not yet available.

Subcommands

info — inspect a disc, image, or file

Lists titles, durations, sizes, and stream details. A lone URL with no destination is the same as freemkv info <url>. Needs no key, even on AACS discs.

freemkv info disc://
freemkv info iso://Disc.iso

Flag	Description
`-f, --full`	List every title (default: the first five, with a “+N more” footer).
`-b, --basic`	Title rows only — omit the per-stream (video/audio/subtitle) detail.
`-v, --verbose`	Add technical detail — AACS version + MKB version, and per-stream PIDs and audio sample rates. A handful of extra fields, not a flood; off by default to keep the listing scannable (turn it on when debugging a mux or AACS issue).
`--share`	Capture the drive’s profile to a zip and print a ready-to-paste GitHub issue for the community drive-compatibility database. On a release build + interactive terminal, freemkv then offers to submit it for you — a `[Y/n]` prompt (default yes) that posts the issue to GitHub if you accept. `--mask` redacts drive serials first. Nothing is sent unless you confirm at that prompt.

verify — check disc health

Scans the main title and reports good / slow / recovered / bad sectors, with chapter + timestamp per damaged region. Writes nothing. Exits 1 if any sector is unrecoverable — scriptable as a pass/fail gate. Defaults to disc://.

freemkv verify

update-keys — refresh the AACS key database

Downloads, verifies, and installs an AACS keydb (.txt / .zip / .gz). --url is required.

freemkv update-keys --url http://example.org/keydb_eng.zip

version / help

freemkv version    # also --version / -V
freemkv help       # also --help / -h (exit 0)

Flags

Key sources (for a rip that needs decryption keys):

Flag	Description
`-k, --keydb PATH`	Optional override for the keydb location. Without it, freemkv searches the default locations — see Decryption Keys. Only Blu-ray/UHD need a keydb; DVDs use none.
`--key-url URL`	Online key service (`https://…`); the local keydb is tried first if both are given.
`--key-auth TOKEN`	Bearer token for `--key-url`.

Title selection (-t) and the iso://-only --raw / --multipass flags are covered under Scheme details.

Global (any command):

Flag	Description
`--language CODE`	UI language (alias `--lang`).
`--log-level N`	Diagnostic log file, 1 = warn … 4 = trace (terminal stays clean; default `./log.txt`). For bug reports use `--log-level 3`.
`--log-file PATH`	Write the log to PATH.
`-q, --quiet`	Suppress stdout.
`RUST_LOG`	Power-user filter; enables file logging and wins over `--log-level`.

Keys are never written to logs. One Ctrl-C halts a rip cleanly (tray unlocked, mapfile preserved); a second forces exit 130.

Exit codes

Code	Meaning
`0`	Success.
`1`	Failed (rip / mux / scan error, bad flag, missing key) or `verify` found unrecoverable sectors.
`2`	No subcommand or URL (usage printed).
`130`	Second Ctrl-C.