Back to Details

moviepilot-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MoviePilot CLI

MoviePilot CLI

All script paths are relative to this skill file.
Use 
scripts/mp-cli.js
to interact with the MoviePilot backend.
所有脚本路径都相对于此技能文件。
使用
scripts/mp-cli.js
与MoviePilot后端交互。

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.
列出所有可用命令：
node scripts/mp-cli.js list
查看指定命令的参数和用法：
node scripts/mp-cli.js show <command>
调用命令前务必先运行
show <command>
——参数名无法推断，请勿猜测。

Command Groups

命令组

CategoryCommands
Media Searchsearch_media, recognize_media, query_media_detail, get_recommendations, search_person, search_person_credits
Torrentsearch_torrents, get_search_results
Downloadadd_download, query_download_tasks, delete_download, query_downloaders
Subscriptionadd_subscribe, query_subscribes, update_subscribe, delete_subscribe, search_subscribe, query_subscribe_history, query_popular_subscribes, query_subscribe_shares
Libraryquery_library_exists, query_library_latest, transfer_file, scrape_metadata, query_transfer_history
Fileslist_directory, query_directory_settings
Sitesquery_sites, query_site_userdata, test_site, update_site, update_site_cookie
Systemquery_schedulers, run_scheduler, query_workflows, run_workflow, query_rule_groups, query_episode_schedule, send_message
分类命令
媒体搜索search_media, recognize_media, query_media_detail, get_recommendations, search_person, search_person_credits
种子search_torrents, get_search_results
下载add_download, query_download_tasks, delete_download, query_downloaders
订阅add_subscribe, query_subscribes, update_subscribe, delete_subscribe, search_subscribe, query_subscribe_history, query_popular_subscribes, query_subscribe_shares
媒体库query_library_exists, query_library_latest, transfer_file, scrape_metadata, query_transfer_history
文件list_directory, query_directory_settings
站点query_sites, query_site_userdata, test_site, update_site, update_site_cookie
系统query_schedulers, run_scheduler, query_workflows, run_workflow, query_rule_groups, query_episode_schedule, send_message

Workflows

工作流程

Search and Download

搜索与下载

1. Search TMDB

1. 搜索TMDB

Search for a movie or TV show by title: 
node scripts/mp-cli.js search_media title="..." media_type="movie"
If the user specifies a TV season, run Season Validation step first — the season number provided by the user may not match TMDB.
按标题搜索电影或电视剧： 
node scripts/mp-cli.js search_media title="..." media_type="movie"
如果用户指定了电视剧季数，请先运行季数验证步骤——用户提供的季数可能与TMDB的季数不匹配。

2. Search torrents

2. 搜索种子

Prefer 
tmdb_id
; use 
douban_id
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 search_torrents tmdb_id=791373 media_type="movie"
Search torrents using user-specified sites (pass site IDs from 
query_sites
): 
node scripts/mp-cli.js search_torrents tmdb_id=791373 media_type="movie" sites='1,3'
When 
search_torrents
returns:
  1. Stop — do not call 
    get_search_results
    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.
优先使用
tmdb_id
；仅当
tmdb_id
不可用时才使用
douban_id
。
省略
sites=
参数时会使用用户的默认站点。如果用户指定了站点，请先获取站点ID： 
node scripts/mp-cli.js query_sites
使用默认站点搜索种子： 
node scripts/mp-cli.js search_torrents tmdb_id=791373 media_type="movie"
使用用户指定的站点搜索种子（传入
query_sites
返回的站点ID）： 
node scripts/mp-cli.js search_torrents tmdb_id=791373 media_type="movie" sites='1,3'
当
search_torrents
返回结果后：
  1. 暂停——暂时不要调用
    get_search_results
    。
  2. 将所有
    filter_options
    字段以及每个字段下的所有值原封不动地展示给用户。
  3. 不要预选、总结或省略任何字段或值。
  4. 等待用户选择筛选条件或确认不需要筛选后，再进入下一步。

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

3. 获取筛选后的结果（仅在用户对filter_options做出响应后执行）

Run 
node scripts/mp-cli.js show get_search_results
to check available parameters. Filter logic: OR within a field, AND across fields.
Filter values must come from the 
filter_options
returned by 
search_torrents
— do not invent, translate, normalize, or use values from any other source. Note: 
filter_options
keys are camelCase (e.g., 
freeState
), but 
get_search_results
params are snake_case (e.g., 
free_state
).
Fetch results with selected filters: 
node scripts/mp-cli.js get_search_results resolution='1080p,2160p' free_state='免费,50%'
If empty, tell the user which filter to relax and ask before retrying.
运行
node scripts/mp-cli.js show get_search_results
查看可用参数。筛选逻辑：同一字段内的条件为OR关系，不同字段间的条件为AND关系。
筛选值必须来自
search_torrents
返回的
filter_options
——不要编造、翻译、标准化或使用任何其他来源的值。注意：
filter_options
的键是驼峰命名（例如
freeState
），但
get_search_results
的参数是蛇形命名（例如
free_state
）。
使用选中的筛选条件获取结果： 
node scripts/mp-cli.js get_search_results resolution='1080p,2160p' free_state='免费,50%'
如果结果为空，告知用户可以放宽哪些筛选条件，重试前请先征求用户同意。

4. Present results as a numbered list

4. 以编号列表展示结果

Show all results without pre-selection. Each row: index, title, size, seeders, resolution, release group, 
volume_factor
, 
freedate_diff
.
volume_factor
Meaning
免费
Free download
50%
50% download size
2X
Double upload
2X免费
Double upload + free
普通
No discount
freedate_diff
: remaining free window (e.g., 
2天3小时
).
无需预选，展示所有结果。每行包含：序号、标题、大小、做种数、分辨率、发布组、
volume_factor
、
freedate_diff
。
volume_factor
含义
免费
免费下载
50%
下载大小减半
2X
双倍上传
2X免费
双倍上传+免费下载
普通
无折扣
freedate_diff
：剩余免费窗口时长（例如
2天3小时
）。

5. Check before downloading

5. 下载前检查

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

6. 添加下载

Download one or more torrents (
torrent_url
comes from 
get_search_results
output): 
node scripts/mp-cli.js add_download torrent_url="abc1234:1,def5678:2"
下载一个或多个种子（
torrent_url
来自
get_search_results
的输出）： 
node scripts/mp-cli.js add_download torrent_url="abc1234:1,def5678:2"

Error handling

错误处理

StepAction
search_media
empty		Retry with alternative title (English/original), inform user. Still empty → ask for title or TMDB ID.
search_torrents
empty		Inform user, ask whether to retry with different sites.
get_search_results
empty		Do not silently broaden filters. Suggest which filter to relax, ask before retrying.
add_download
fails		Run 
query_downloaders
+ 
query_download_tasks
to diagnose, then report to user.
步骤操作
search_media
无结果		使用备选标题（英文/原名）重试，告知用户。如果仍然无结果→请用户提供标题或TMDB ID。
search_torrents
无结果		告知用户，询问是否更换站点重试。
get_search_results
无结果		不要悄悄放宽筛选条件。建议可以放宽的筛选条件，重试前先征求用户同意。
add_download
失败		运行
query_downloaders
+ 
query_download_tasks
排查问题，然后告知用户。

Add Subscription

添加订阅

  1. Search for the media to get 
    tmdb_id
    : Run 
    search_media
    .
  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 add_subscribe title="..." year="2011" media_type="tv" tmdb_id=42009
Subscribe to a specific season: 
node scripts/mp-cli.js add_subscribe title="..." year="2011" media_type="tv" tmdb_id=42009 season=4
Subscribe starting from a specific episode: 
node scripts/mp-cli.js add_subscribe title="..." year="2024" media_type="tv" tmdb_id=12345 season=1 start_episode=13
  1. 搜索媒体获取
    tmdb_id
    ：运行
    search_media
    。
  2. 运行媒体库与订阅检查步骤，如果媒体已存在或已被订阅，停止操作并告知用户。
  3. 如果用户指定了电视剧季数，请先运行季数验证步骤。
订阅电影或电视剧： 
node scripts/mp-cli.js add_subscribe title="..." year="2011" media_type="tv" tmdb_id=42009
订阅指定季： 
node scripts/mp-cli.js add_subscribe title="..." year="2011" media_type="tv" tmdb_id=42009 season=4
从指定集开始订阅： 
node scripts/mp-cli.js add_subscribe title="..." year="2024" media_type="tv" tmdb_id=12345 season=1 start_episode=13

Manage Downloads

下载管理

List download tasks and get hash for further operations: 
node scripts/mp-cli.js query_download_tasks status=downloading
Delete a download task (confirm with user first — irreversible): 
node scripts/mp-cli.js delete_download hash=<hash>
Delete a download task and also remove its files (confirm with user first — irreversible): 
node scripts/mp-cli.js delete_download hash=<hash> delete_files=true
列出下载任务并获取后续操作所需的哈希值： 
node scripts/mp-cli.js query_download_tasks status=downloading
删除下载任务（操作不可撤销，请先征得用户同意）： 
node scripts/mp-cli.js delete_download hash=<hash>
删除下载任务并移除相关文件（操作不可撤销，请先征得用户同意）： 
node scripts/mp-cli.js delete_download 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 update_subscribe subscribe_id=123 resolution="1080p"
Trigger a search for missing episodes (confirm with user first): 
node scripts/mp-cli.js search_subscribe subscribe_id=123
Remove a subscription (confirm with user first): 
node scripts/mp-cli.js delete_subscribe subscribe_id=123
列出活跃订阅： 
node scripts/mp-cli.js query_subscribes status=R
更新订阅筛选条件： 
node scripts/mp-cli.js update_subscribe subscribe_id=123 resolution="1080p"
触发缺失剧集的搜索（请先征得用户同意）： 
node scripts/mp-cli.js search_subscribe subscribe_id=123
删除订阅（操作不可撤销，请先征得用户同意）： 
node scripts/mp-cli.js delete_subscribe subscribe_id=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 query_library_exists tmdb_id=123456 media_type="movie"
Check if the media is already subscribed: 
node scripts/mp-cli.js query_subscribes tmdb_id=123456
在任何下载或订阅操作前运行，避免重复。
检查媒体是否已存在于媒体库中： 
node scripts/mp-cli.js query_library_exists tmdb_id=123456 media_type="movie"
检查媒体是否已被订阅： 
node scripts/mp-cli.js query_subscribes tmdb_id=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".
用户指定季数时必须执行此步骤。有时制作方会在TMDB的同一季下分多部分发布剧集，而社区和种子站点可能会将每个部分标记为单独的“季”。

1. Verify season exists

1. 验证季数是否存在

Fetch media detail to check available seasons: 
node scripts/mp-cli.js query_media_detail tmdb_id=<id> media_type="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.
获取媒体详情查看可用季数： 
node scripts/mp-cli.js query_media_detail tmdb_id=<id> media_type="tv"
将
season_info
与用户请求的季数进行对比：
  1. 如果
    season_info
    中存在该季→直接使用该季号，返回调用的工作流程。
  2. 如果
    season_info
    中不存在该季→用户所说的“季”很可能对应TMDB现有某一季中靠后的剧集范围。记下
    season_info
    中最新（编号最大）的季数，继续下一步。

2. Identify the correct episode range

2. 确定正确的剧集范围

Fetch episode schedule for the latest season from 
season_info
: 
node scripts/mp-cli.js query_episode_schedule tmdb_id=<id> season=<latest_season_number>
Use 
air_date
to find a block of recently-aired episodes that likely corresponds to what the user calls the missing season. Look for a gap in 
air_date
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.
获取
season_info
中最新一季的剧集播出时间表： 
node scripts/mp-cli.js query_episode_schedule tmdb_id=<id> season=<latest_season_number>
使用
air_date
（播出日期）找到最近播出的剧集块，这部分很可能对应用户所说的缺失季数。查找剧集
air_date
之间的间隔——间隔表示部分拆分，间隔后的剧集很可能就是用户所说的下一“季”。例如，如果TMDB第1季包含1-24集，第12集和第13集之间有几个月的间隔，那么13-24集就对应用户所说的“第2季”。如果不存在这样的间隔，告知用户内容不可用。否则请与用户确认剧集范围。

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>
配置缺失：请用户提供后端地址和API密钥。获取后请持久化保存配置——后续命令会自动使用该配置： 
node scripts/mp-cli.js -h <HOST> -k <KEY>