mosaic-cli

Every Mosaic pipeline from the terminal — scripts, CI jobs, headless servers. Same ffmpeg pipelines as the desktop app, no UI.

mosaic-cli sheet movie.mkv

Install

macOS & Linux

curl -LsSf https://mosaicvideo.github.io/mosaic/install.sh | sh

Installs to ~/.local/bin by default. Override with MOSAIC_INSTALL_DIR:

curl -LsSf https://mosaicvideo.github.io/mosaic/install.sh | MOSAIC_INSTALL_DIR=/usr/local/bin sh

Windows (PowerShell)

irm https://mosaicvideo.github.io/mosaic/install.ps1 | iex

Installs to %LOCALAPPDATA%\Programs\mosaic-cli and adds it to user PATH. Restart your terminal afterward.

Manual download

If you'd rather avoid the one-liner, grab a binary directly from the latest release:

01.
mac
mosaic-cli-macos-universal
--
02.
windows
mosaic-cli-windows-x86_64.exe
--
03.
win-arm
mosaic-cli-windows-aarch64.exe
--
04.
linux
mosaic-cli-linux-x86_64
--

On macOS/Linux, make executable and move onto PATH:

chmod +x mosaic-cli-*
mv mosaic-cli-* ~/.local/bin/mosaic-cli

Verify checksum

Each release ships a SHA256SUMS file covering every CLI artifact. To verify:

curl -LO https://github.com/mosaicvideo/mosaic/releases/latest/download/SHA256SUMS
grep " mosaic-cli-macos-universal$" SHA256SUMS | shasum -a 256 -c -

Expected output: mosaic-cli-macos-universal: OK. The one-liner install scripts do this automatically.

Requirements

mosaic-cli shells out to ffmpeg, ffprobe, and mediainfo — all three must be on your PATH. The macOS build of ffmpeg from Homebrew's default bottle is missing the drawtext filter; install ffmpeg-full instead.

See the GUI guide's Requirements section for per-platform install commands.

Quick start

# One still contact sheet
mosaic-cli sheet movie.mkv

# 12 screenshots into a specific folder
mosaic-cli screenshots --count 12 -o shots/ movie.mkv

# Animated preview reel: 10 clips at 2 seconds each
mosaic-cli reel --count 10 --clip-length 2 movie.mkv

# Animated contact sheet, 4×3 grid
mosaic-cli animated-sheet --cols 4 --rows 3 movie.mkv

Inputs can be files or directories. Directories are scanned recursively by default; pass --no-recursive to stay shallow. Stdout is paths-only so output pipes cleanly into xargs; progress and summaries go to stderr.

Subcommands

screenshots

Capture individual frames from a video at evenly-spaced timestamps.

mosaic-cli screenshots [OPTIONS] <INPUT>...

Common flags:

  • --count N — number of frames (default: 8)
  • --format png|jpeg — output format (default: png)
  • --quality N — JPEG quality 50–100 (default: 92)
  • --suffix S — filename infix between stem and index (default: _screens_)
  • -o DIR — output directory (default: next to each source)
mosaic-cli screenshots --count 20 --format jpeg --quality 90 -o shots/ movie.mkv

sheet

Generate a still contact sheet — a grid of thumbnails with an optional metadata header.

mosaic-cli sheet [OPTIONS] <INPUT>...

Common flags:

  • --cols N — columns (default: 3)
  • --rows N — rows (default: 6)
  • --width PX — total sheet width (default: 1920)
  • --gap PX — thumbnail spacing (default: 10)
  • --format png|jpeg — output format (default: png)
  • --quality N — JPEG quality 50–100 (default: 92)
  • --theme dark|light — color theme (default: dark)
  • --no-timestamps / --timestamps — toggle per-thumbnail timestamp overlay
  • --no-header / --header — toggle the metadata header band
  • --suffix S — filename infix (default: _sheet)
mosaic-cli sheet --cols 4 --rows 5 --width 2400 --theme light movie.mkv

reel

Stitch short clips into a single animated preview reel (WebP/WebM/GIF).

mosaic-cli reel [OPTIONS] <INPUT>...

Common flags:

  • --count N — number of clips (default: 15)
  • --clip-length SECS — seconds per clip (default: 2)
  • --height PX — output height; width follows aspect ratio (default: 360)
  • --fps N — frame rate, capped at source fps (default: 24)
  • --format webp|webm|gif — output container (default: webp)
  • --quality N — encoder quality 0–100 (default: 75; ignored for GIF)
  • --suffix S — filename infix (default: _reel)
mosaic-cli reel --count 8 --clip-length 3 --format gif movie.mkv

animated-sheet

Grid of animated clips — a contact sheet where every cell is a short looping WebP. Output is always WebP.

mosaic-cli animated-sheet [OPTIONS] <INPUT>...

Common flags:

  • --cols N — columns (default: 3)
  • --rows N — rows (default: 6)
  • --width PX — total sheet width (default: 1280)
  • --gap PX — thumbnail spacing (default: 8)
  • --clip-length SECS — seconds per animated cell (default: 2)
  • --fps N — animated frame rate (default: 12)
  • --quality N — WebP encoder quality (default: 75)
  • --theme dark|light — color theme (default: dark)
  • --suffix S — filename infix (default: _animated_sheet)

probe

Print the parsed ffprobe result as JSON. With --mediainfo, wraps both ffprobe and raw MediaInfo output in an envelope.

mosaic-cli probe [--mediainfo] <INPUT>
mosaic-cli probe movie.mkv | jq .duration_secs
mosaic-cli probe --mediainfo movie.mkv | jq .ffprobe.video.color_transfer

completions

Emit a shell-completion script to stdout.

mosaic-cli completions <bash|zsh|fish|powershell|elvish>

See Shell completions for setup instructions per shell.

manpage

Emit a roff-formatted man page to stdout.

mosaic-cli manpage

See Man page for install instructions.

Config file

On first run, mosaic-cli creates ~/.mosaic-cli.toml with every option commented out. Uncomment any key to change its default. The full precedence is:

  1. Command-line flags (highest)
  2. Config file at $MOSAIC_CLI_CONFIG (if set) or ~/.mosaic-cli.toml
  3. Built-in defaults shown in each subcommand above

Example config:

[sheet]
cols = 4
rows = 6
theme = "light"
suffix = "_thumbs"

[reel]
count = 12
clip_length_secs = 3
format = "gif"

Note: the config key for reel/animated-sheet clip duration is clip_length_secs (TOML convention, unit explicit), while the CLI flag is --clip-length. The difference is intentional.

Shell completions

zsh:

mkdir -p ~/.zfunc
mosaic-cli completions zsh > ~/.zfunc/_mosaic-cli

Ensure these lines are in ~/.zshrc before compinit:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

bash:

mkdir -p ~/.local/share/bash-completion/completions
mosaic-cli completions bash > ~/.local/share/bash-completion/completions/mosaic-cli

fish:

mkdir -p ~/.config/fish/completions
mosaic-cli completions fish > ~/.config/fish/completions/mosaic-cli.fish

PowerShell:

# temporarily (current session only):
mosaic-cli completions powershell | Out-String | Invoke-Expression

# persistently (append to your profile):
mosaic-cli completions powershell | Out-String | Add-Content $PROFILE

Man page

mkdir -p ~/.local/share/man/man1
mosaic-cli manpage > ~/.local/share/man/man1/mosaic-cli.1
man mosaic-cli

If your MANPATH doesn't include ~/.local/share/man, add it to your shell rc:

export MANPATH="$HOME/.local/share/man:$MANPATH"

Upgrading

Re-run the install script. The version is resolved at runtime, so the same one-liner always fetches the latest release.

Uninstalling

macOS / Linux:

rm ~/.local/bin/mosaic-cli
rm ~/.mosaic-cli.toml           # optional: config file

Windows:

Remove-Item "$env:LOCALAPPDATA\Programs\mosaic-cli" -Recurse

Remove the install dir from user PATH via Settings → System → About → Advanced system settings → Environment Variables.

Troubleshooting

ffmpeg not found on PATH — install ffmpeg, ffprobe, and mediainfo. See Requirements.

Gatekeeper blocks the macOS binary — shouldn't happen (the macOS CLI is signed and notarized with the same Developer ID as the GUI). If it does, clear the quarantine attribute:

xattr -d com.apple.quarantine ~/.local/bin/mosaic-cli

SmartScreen warning on Windows — the Windows CLI is unsigned. If you downloaded manually via Explorer, Windows may mark the file. Run the one-liner installer instead (programmatic download avoids Mark-of-the-Web), or unblock via PowerShell:

Unblock-File -Path "$env:LOCALAPPDATA\Programs\mosaic-cli\mosaic-cli.exe"

Arch mismatch error from install.sh — Linux aarch64 builds aren't published. Build from source with cargo build --release --manifest-path mosaic-cli/Cargo.toml or open an issue for a prebuilt.

Checksum mismatch — re-run the installer (network glitches can produce partial downloads). If it persists, file an issue and include the release tag + platform.

GitHub API rate limit from install.sh — unauthenticated requests are capped at 60/hour per IP. If you're behind a shared NAT and hit the limit, pin the version:

curl -LsSf https://mosaicvideo.github.io/mosaic/install.sh | MOSAIC_VERSION=v0.1.5 sh