moviebox-v1 CLI Reference¶

Search, download, and stream movies and TV series with subtitle support.

Environment Variable Prefix

All environment variable overrides use the prefix MOVIEBOX_. For example, the API host can be set via MOVIEBOX_API_HOST.

Global Options¶

moviebox-v1 [OPTIONS] COMMAND [ARGS]...

Option	Description
`--version`	Show the version and exit
`--help`	Show this message and exit

Commands¶

Command	Description
`download-movie`	Search and download or stream a movie
`download-series`	Search and download or stream a TV series
`homepage-content`	Show contents displayed at the landing page
`item-details`	Show details of a particular movie/TV series
`mirror-hosts`	Discover Moviebox mirror hosts
`popular-search`	Show movies/TV series many people are searching now

download-movie¶

Search and download or stream a movie.

moviebox-v1 download-movie [OPTIONS] TITLE

Arguments¶

Argument	Description
`TITLE`	Title of the movie to search for (required)

Options¶

Search & Selection¶

Option	Type	Default	Description
`-y, --year`	`INTEGER`	`0`	Year filter for the movie
`-q, --quality`	`worst\\|best\\|360p\\|480p\\|720p\\|1080p`	`best`	Media quality to download
`-Y, --yes`	flag	—	Skip movie confirmation prompt

Output Paths¶

Option	Type	Default	Description
`-d, --dir`	`DIRECTORY`	`$PWD`	Directory to save the movie file
`-D, --caption-dir`	`DIRECTORY`	`$PWD`	Directory to save the caption file
`-P, --part-dir`	`DIRECTORY`	`$PWD`	Directory for temporary download part files

File Naming¶

Option	Type	Default	Description
`-M, --movie-filename-tmpl`	`TEXT`	`{title} ({release_year}).{ext}`	Template for the movie filename
`-C, --caption-filename-tmpl`	`TEXT`	`{title} ({release_year}).{lan}.{ext}`	Template for the caption filename
`-E, --part-extension`	`TEXT`	`.part`	File extension for download part files

Caption Options¶

Option	Type	Default	Description
`-x, --language`	`TEXT`	`English`	Caption language filter
`--caption / --no-caption`	flag	`caption`	Enable or disable caption download
`-O, --caption-only`	flag	—	Download caption file only; skip movie
`-I, --ignore-missing-caption`	flag	—	Proceed with movie download even if caption is missing

Download Behaviour¶

Option	Type	Default	Description
`-m, --mode`	`start\\|resume\\|auto`	`auto`	Download mode: start fresh, resume, or detect automatically
`-t, --tasks`	`INTEGER (1–1000)`	`5`	Number of concurrent download tasks
`-N, --chunk-size`	`INTEGER`	`256`	Streaming chunk size in kilobytes
`-R, --timeout-retry-attempts`	`INTEGER`	`10`	Retry attempts on read timeout
`-B, --merge-buffer-size`	`INTEGER (1–102400)`	`CHUNK_SIZE`	Buffer size (KB) for merging part files
`-T, --test`	flag	—	Test download viability without actually downloading

Streaming¶

Option	Type	Default	Description
`-X, --stream-via`	`mpv\\|vlc`	—	Stream directly via the chosen media player instead of downloading

Progress Bar¶

Option	Type	Default	Description
`-c, --colour`	`TEXT`	`cyan`	Progress bar colour
`-U, --ascii`	flag	—	Use Unicode smooth blocks for the progress bar meter
`-z, --disable-progress-bar`	flag	—	Suppress the download progress bar
`-S, --simple`	flag	—	Show percentage and bar only (no extra info)
`--leave / --no-leave`	flag	`no-leave`	Keep all progress bar leaves after completion

Logging¶

Option	Type	Default	Description
`-V, --verbose`	flag	—	Show detailed interactive output
`-Q, --quiet`	flag	—	Suppress all interactive output/logs

Examples¶

# Download best quality, auto-detect resume
moviebox-v1 download-movie "Inception"

# Download 720p, skip confirmation, save to ~/Movies
moviebox-v1 download-movie "Inception" -q 720p -Y -d ~/Movies

# Download 1080p from a specific year, ignore missing subtitles
moviebox-v1 download-movie "The Batman" -y 2022 -q 1080p -I

# Stream directly with mpv
moviebox-v1 download-movie "Inception" -X mpv

# Download caption file only
moviebox-v1 download-movie "Inception" -O

# Test download without fetching
moviebox-v1 download-movie "Inception" -T

download-series¶

Search and download or stream a TV series.

moviebox-v1 download-series [OPTIONS] TITLE

Arguments¶

Argument	Description
`TITLE`	Title of the TV series to search for (required)

Options¶

Search & Selection¶

Option	Type	Default	Description
`-y, --year`	`INTEGER`	`0`	Year filter for the series
`-s, --season`	`INTEGER (1–1000)`	—	Season number (required)
`-e, --episode`	`INTEGER (1–1000)`	—	Episode offset within the season (required)
`-l, --limit`	`INTEGER (1–1000)`	`1`	Total number of episodes to download
`-q, --quality`	`worst\\|best\\|360p\\|480p\\|720p\\|1080p`	`best`	Media quality to download
`-Y, --yes`	flag	—	Skip series confirmation prompt
`-A, --auto-mode`	flag	—	When limit is 1 (default), download all remaining episodes in the season

Output Paths¶

Option	Type	Default	Description
`-d, --dir`	`DIRECTORY`	`$PWD`	Directory to save the series files
`-D, --caption-dir`	`DIRECTORY`	`$PWD`	Directory to save caption files
`-P, --part-dir`	`DIRECTORY`	`$PWD`	Directory for temporary download part files

File Naming & Structure¶

Option	Type	Default	Description
`-L, --episode-filename-tmpl`	`TEXT`	`{title} S{season}E{episode}.{ext}`	Template for episode filenames
`-C, --caption-filename-tmpl`	`TEXT`	`{title} S{season}E{episode}.{lan}.{ext}`	Template for caption filenames
`-E, --part-extension`	`TEXT`	`.part`	File extension for download part files
`-f, --format`	`standard\\|group\\|struct`	—	Episode file organisation format (see below)

Format Modes

Mode	Description	Example
`standard`	Save all episodes flat in the output directory	`Merlin S1E2.mp4`
`group`	Organise episodes into per-season subdirectories	`Merlin/S1/Merlin S1E2.mp4`
`struct`	Hierarchical directory structure	`Merlin (2009)/S1/E1.mp4`

Caption Options¶

Option	Type	Default	Description
`-x, --language`	`TEXT`	`English`	Caption language filter
`--caption / --no-caption`	flag	`caption`	Enable or disable caption download
`-O, --caption-only`	flag	—	Download caption files only; skip video
`-I, --ignore-missing-caption`	flag	—	Proceed with episode download even if caption is missing

Download Behaviour¶

Option	Type	Default	Description
`-m, --mode`	`start\\|resume\\|auto`	`auto`	Download mode: start fresh, resume, or detect automatically
`-t, --tasks`	`INTEGER (1–1000)`	`5`	Number of concurrent download tasks
`-N, --chunk-size`	`INTEGER`	`256`	Streaming chunk size in kilobytes
`-R, --timeout-retry-attempts`	`INTEGER`	`10`	Retry attempts on read timeout
`-B, --merge-buffer-size`	`INTEGER (1–102400)`	`CHUNK_SIZE`	Buffer size (KB) for merging part files
`-T, --test`	flag	—	Test download viability without actually downloading

Streaming¶

Option	Type	Default	Description
`-X, --stream-via`	`mpv\\|vlc`	—	Stream directly via the chosen media player

Progress Bar¶

Option	Type	Default	Description
`-c, --colour`	`TEXT`	`cyan`	Progress bar colour
`-U, --ascii`	flag	—	Use Unicode smooth blocks for the progress bar meter
`-z, --disable-progress-bar`	flag	—	Suppress the download progress bar
`-S, --simple`	flag	—	Show percentage and bar only
`--leave / --no-leave`	flag	`no-leave`	Keep all progress bar leaves after completion

Logging¶

Option	Type	Default	Description
`-V, --verbose`	flag	—	Show detailed interactive output
`-Q, --quiet`	flag	—	Suppress all interactive output/logs

Examples¶

# Download S1E1 of Merlin
moviebox-v1 download-series "Merlin" -s 1 -e 1

# Download episodes 3–7 of Season 2, 720p, organised into folders
moviebox-v1 download-series "Merlin" -s 2 -e 3 -l 5 -q 720p -f group

# Download all remaining episodes in season 1 starting from E1
moviebox-v1 download-series "The Last Kingdom" -s 1 -e 1 -A

# Stream S1E1 directly with VLC
moviebox-v1 download-series "Into the Badlands" -s 1 -e 1 -X vlc

# Download captions only for S3E1
moviebox-v1 download-series "Merlin" -s 3 -e 1 -O

# Download with hierarchical folder structure, skip confirmation
moviebox-v1 download-series "Merlin" -s 1 -e 1 -l 13 -f struct -Y -d ~/Series

homepage-content¶

Show contents displayed at the Moviebox landing page.

moviebox-v1 homepage-content [OPTIONS]

Options¶

Option	Type	Default	Description
`-J, --json`	flag	`False`	Output details in JSON format
`-T, --title`	`TEXT`	`None`	Filter contents by title
`-B, --banner`	flag	`False`	Show banner content only
`-V, --verbose`	flag	—	Show detailed interactive output
`-Q, --quiet`	flag	—	Suppress all interactive output/logs

Examples¶

# List all homepage content
moviebox-v1 homepage-content

# Filter by title keyword
moviebox-v1 homepage-content -T "action"

# Output as JSON
moviebox-v1 homepage-content -J

# Show banner items only
moviebox-v1 homepage-content -B

item-details¶

Show details for a specific movie or TV series.

moviebox-v1 item-details [OPTIONS] TITLE

Arguments¶

Argument	Description
`TITLE`	Title to look up (required)

Options¶

Option	Type	Default	Description
`-y, --year`	`INTEGER`	`0`	Year filter for the item
`-s, --subject-type`	`all\\|movies\\|tv_series\\|education\\|music\\|anime`	`all`	Subject type filter
`-Y, --yes`	flag	—	Skip item confirmation prompt
`-J, --json`	flag	—	Output details in JSON format instead of tabulated
`-F, --full`	flag	—	Show all available details
`-V, --verbose`	flag	—	Show detailed interactive output
`-Q, --quiet`	flag	—	Suppress all interactive output/logs

Examples¶

# Look up a movie
moviebox-v1 item-details "Inception"

# Look up a TV series with year filter
moviebox-v1 item-details "Merlin" -y 2008 -s tv_series

# Output full details as JSON
moviebox-v1 item-details "Inception" -J -F

# Skip confirmation prompt
moviebox-v1 item-details "The Batman" -y 2022 -Y

mirror-hosts¶

Discover available Moviebox mirror hosts.

moviebox-v1 mirror-hosts [OPTIONS]

Environment Variable

The API host can also be set via the MOVIEBOX_API_HOST environment variable.

Options¶

Option	Type	Default	Description
`-J, --json`	flag	—	Output discovered hosts in JSON format
`-V, --verbose`	flag	—	Show detailed interactive output
`-Q, --quiet`	flag	—	Suppress all interactive output/logs

Examples¶

# List available mirror hosts
moviebox-v1 mirror-hosts

# Output as JSON
moviebox-v1 mirror-hosts -J

# Set host via environment variable
MOVIEBOX_API_HOST=https://mirror.example.com moviebox-v1 mirror-hosts

popular-search¶

Show movies and TV series that many users are currently searching for.

moviebox-v1 popular-search [OPTIONS]

Options¶

Option	Type	Default	Description
`-J, --json`	flag	`False`	Output results in JSON format

Examples¶

# Show popular searches (tabulated)
moviebox-v1 popular-search

# Output as JSON
moviebox-v1 popular-search -J

Filename Templates¶

Both download-movie and download-series support customisable filename templates using placeholder variables.

Video File Placeholders (`-M`, `-L`)¶

Placeholder	Description
`{title}`	Title of the movie or series
`{release_year}`	Release year
`{release_date}`	Full release date
`{resolution}`	Video resolution (e.g. `1080p`)
`{ext}`	File extension
`{size_string}`	Human-readable file size
`{season}`	Season number (series only)
`{episode}`	Episode number (series only)
`{episode_title}`	Episode title (series only)
`{duration}`	Media duration
`{codec_name}`	Video codec name

Caption File Placeholders (`-C`)¶

Placeholder	Description
`{title}`	Title of the movie or series
`{release_year}`	Release year
`{release_date}`	Full release date
`{ext}`	File extension
`{size_string}`	Human-readable file size
`{id}`	Caption track identifier
`{lan}`	Caption language code (e.g. `en`)
`{lan_name}`	Caption language full name (e.g. `English`)
`{delay}`	Caption sync delay value
`{season}`	Season number (series only)
`{episode}`	Episode number (series only)
`{episode_title}`	Episode title (series only)

Defaults¶

Movie file:    {title} ({release_year}).{ext}
Movie caption: {title} ({release_year}).{lan}.{ext}

Episode file:    {title} S{season}E{episode}.{ext}
Episode caption: {title} S{season}E{episode}.{lan}.{ext}

Common Flags Reference¶

These flags are shared across multiple commands:

Flag	Commands	Description
`-V, --verbose`	all	Show detailed interactive output
`-Q, --quiet`	all	Suppress all interactive output/logs
`-J, --json`	most	Output in JSON format
`-Y, --yes`	download, item-details	Skip confirmation prompts
`-T, --test`	download commands	Test without downloading
`-X, --stream-via`	download commands	Stream via `mpv` or `vlc`
`-O, --caption-only`	download commands	Fetch captions only
`-I, --ignore-missing-caption`	download commands	Proceed even if caption is absent

moviebox-v1 CLI Reference¶

Global Options¶

Commands¶

download-movie¶

Arguments¶

Options¶

Search & Selection¶

Output Paths¶

File Naming¶

Caption Options¶

Download Behaviour¶

Streaming¶

Progress Bar¶

Logging¶

Examples¶

download-series¶

Arguments¶

Options¶

Search & Selection¶

Output Paths¶

File Naming & Structure¶

Caption Options¶

Download Behaviour¶

Streaming¶

Progress Bar¶

Logging¶

Examples¶

homepage-content¶

Options¶

Examples¶

item-details¶

Arguments¶

Options¶

Examples¶

mirror-hosts¶

Options¶

Examples¶

popular-search¶

Options¶

Examples¶

Filename Templates¶

Video File Placeholders (-M, -L)¶

Caption File Placeholders (-C)¶

Defaults¶

Common Flags Reference¶

Video File Placeholders (`-M`, `-L`)¶

Caption File Placeholders (`-C`)¶