MoviePilot CLI

All script paths are relative to this skill file.

Use scripts/mp-cli.js to interact with the MoviePilot backend.

Discover Commands

List all available commands: node scripts/mp-cli.js list

Show parameters and usage for a specific command: node scripts/mp-cli.js show <command>

Always run show <command> before calling a command — parameter names are not inferable, do not guess.

Command Groups

Workflows

Search and Download

1. Search TMDB

Search for a movie or TV show by title: node scripts/mp-cli.js searchmedia title="..." mediatype="movie"

If the user specifies a TV season, run Season Validation step first — the season number provided by the user may not match TMDB.

2. Search torrents

Prefer tmdbid; use doubanid only when tmdb_id is unavailable.

Omitting sites= uses the user's default sites. If the user specifies sites, first retrieve site IDs: node scripts/mp-cli.js query_sites

Search torrents using default sites: node scripts/mp-cli.js searchtorrents tmdbid=791373 media_type="movie"

Search torrents using user-specified sites (pass site IDs from querysites): node scripts/mp-cli.js searchtorrents tmdbid=791373 mediatype="movie" sites='1,3'

When search_torrents returns:

1. Stop — do not call getsearchresults yet.
2. Present all filter_options fields and every value within each field to the user verbatim.
3. Do not pre-select, summarize, or omit any field or value.
4. Wait for the user to select filters or confirm no filters are needed before moving to the next step.

3. Get filtered results (only after user has responded to filter_options)

Run node scripts/mp-cli.js show getsearchresults to check available parameters. Filter logic: OR within a field, AND across fields.

Filter values must come from the filteroptions returned by searchtorrents — do not invent, translate, normalize, or use values from any other source. Note: filteroptions keys are camelCase (e.g., freeState), but getsearchresults params are snakecase (e.g., free_state).

Fetch results with selected filters: node scripts/mp-cli.js getsearchresults resolution='1080p,2160p' free_state='免费,50%'

If empty, tell the user which filter to relax and ask before retrying.

4. Present results as a numbered list

Show all results without pre-selection. Each row: index, title, size, seeders, resolution, release group, volumefactor, freedatediff.

freedate_diff: remaining free window (e.g., 2天3小时).

5. Check before downloading

After the user picks torrents: Run Check Library and Subscriptions step.

If the media already exists in the library or is already subscribed, stop and report the finding to the user.

6. Add download

Download one or more torrents (torrenturl comes from getsearchresults output): node scripts/mp-cli.js adddownloadtasks torrenturl="abc1234:1,def5678:2"

Error handling

Add Subscription

1. Search for the media to get tmdbid: Run searchmedia.
2. Run Check Library and Subscriptions step, if media already exists or is subscribed, stop and report to user.
3. If the user specifies a TV season, run Season Validation step first.

Subscribe to a movie or TV show: node scripts/mp-cli.js addsubscribe title="..." year="2011" mediatype="tv" tmdb_id=42009

Subscribe to a specific season: node scripts/mp-cli.js addsubscribe title="..." year="2011" mediatype="tv" tmdb_id=42009 season=4

Subscribe starting from a specific episode: node scripts/mp-cli.js addsubscribe title="..." year="2024" mediatype="tv" tmdbid=12345 season=1 startepisode=13

Manage Downloads

List download tasks and get hash for further operations: node scripts/mp-cli.js querydownloadtasks status=downloading

Use status=completed for tasks that are neither downloading nor paused in the downloader; use status=all to include every MoviePilot-tagged downloader task. Add includealltags=true when diagnosing tasks that do not have the MoviePilot built-in tag. Add include_trackers=true or query by hash when tracker URLs are needed.

Update a download task (supports start/stop, tags, speed limits, trackers, save path, category, ratio, and seeding time where the downloader supports them): node scripts/mp-cli.js updatedownloadtasks hash=<hash> action=stop uploadlimit=512 downloadlimit=2048

Add trackers to a download task: node scripts/mp-cli.js updatedownloadtasks hash=<hash> trackers='https://tracker.example/announce,udp://tracker.example:80/announce';

Delete a download task (confirm with user first — irreversible): node scripts/mp-cli.js deletedownloadtasks hash=<hash>

Delete a download task and also remove its files (confirm with user first — irreversible): node scripts/mp-cli.js deletedownloadtasks hash=<hash> delete_files=true

Manage Subscriptions

List active subscriptions: node scripts/mp-cli.js query_subscribes status=R

Update subscription filters: node scripts/mp-cli.js updatesubscribe subscribeid=123 resolution="1080p"

Only download full-season packs for a TV best-version subscription: node scripts/mp-cli.js updatesubscribe subscribeid=123 bestversion=1 bestversion_full=1

Trigger a search for missing episodes (confirm with user first): node scripts/mp-cli.js searchsubscribe subscribeid=123

Remove a subscription (confirm with user first): node scripts/mp-cli.js deletesubscribe subscribeid=123

Check Library and Subscriptions

Run before any download or subscription to avoid duplicates.

Check if the media already exists in the library: node scripts/mp-cli.js querylibraryexists tmdbid=123456 mediatype="movie"

Check if the media is already subscribed: node scripts/mp-cli.js querysubscribes tmdbid=123456

Season Validation

Mandatory when user specifies a season. Productions sometimes release a show in multiple parts under one TMDB season; online communities and torrent sites may label each part as a separate "season".

1. Verify season exists

Fetch media detail to check available seasons: node scripts/mp-cli.js querymediadetail tmdbid=<id> mediatype="tv"

Compare season_info with the user's requested season:

1. If the season exists in season_info → use that season number directly and return to the calling workflow.
2. If the season does not exist → the user's "season" likely maps to a later episode range within an existing TMDB season. Note the latest (highest-numbered) season from season_info, then continue to next step.

2. Identify the correct episode range

Fetch episode schedule for the latest season from seasoninfo: node scripts/mp-cli.js queryepisodeschedule tmdbid=<id> season=<latestseasonnumber>

Use airdate to find a block of recently-aired episodes that likely corresponds to what the user calls the missing season. Look for a gap in airdate between episodes — the gap indicates a part break, and the episodes after the gap are what the user likely refers to as the next "season". For example, if TMDB Season 1 has episodes 1–24 and there is a multi-month gap between episode 12 and 13, then episodes 13–24 correspond to the user's "Season 2". If no such gap exists, tell user content is unavailable. Otherwise confirm the episode range with user.

Error handling

Missing configuration: Ask the user for the backend host and API key. Once provided, save the config persistently — subsequent commands will use it automatically: node scripts/mp-cli.js -h <HOST> -k <KEY>