/moviepilot-cli

name: moviepilot-cli
version: 6
description: >-
  Use this skill when the user asks to operate MoviePilot through the local
  `moviepilot tool` MCP CLI for normal product workflows: media search, torrent
  search, downloads, subscriptions, downloader tasks, library checks, sites,
  schedulers, workflows, and messages. Prefer dedicated skills for slash command
  dispatch, manual file organization or failed transfer retry, direct REST API
  calls, direct database SQL, browser operations, and restart/upgrade.

MoviePilot CLI

> All script paths are relative to this skill file.

Use local `moviepilot tool ...` commands to interact with MoviePilot MCP tools. The command reads the local MoviePilot configuration; do not ask the user for `API_TOKEN`, database passwords, or a backend DSN during normal local use.

Scope And Boundaries

This skill is for normal MoviePilot product operations exposed as MCP tools. Choose other skills first when they match more precisely:

| Request | Preferred skill | |---|---| | Slash commands or plugin/system command dispatch | `command-dispatch` | | Manual file organization | `organize-files` | | Retry failed transfer history records | `transfer-failed-retry` | | Direct REST endpoint not exposed by MCP tools | `moviepilot-api` | | Direct SQL query or database update | `database-operation` | | Restart, version check, or upgrade | `moviepilot-update` | | Browser-only state, site login pages, screenshots, cookies | `browser-use` |

Use `moviepilot-api` only after `moviepilot tool list` and `moviepilot tool show <command>` confirm that no MCP tool covers the required operation. Use `database-operation` only when the task explicitly requires SQL inspection or mutation, or when product tools/API cannot answer the data question.

Discover Commands

List all available commands: `moviepilot tool list`

Show parameters and usage for a specific command: `moviepilot tool show <command>`

The tool list includes tools declared by enabled plugins. Re-run `tool list` and `tool show` after a plugin is enabled, disabled, reloaded, or reconfigured so the command selection uses the refreshed runtime registry.

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

Command Groups

| Category | Commands | |---|---| | Media Search | search_media, recognize_media, query_media_detail, get_recommendations, search_person, search_person_credits | | Torrent | search_torrents, get_search_results | | Download | add_download_tasks, query_download_tasks, update_download_tasks, delete_download_tasks, query_downloaders | | Subscription | add_subscribe, query_subscribes, update_subscribe, delete_subscribe, search_subscribe, query_subscribe_history, query_popular_subscribes, query_subscribe_shares | | Library | query_library_exists, query_library_latest, transfer_file, scrape_metadata, query_transfer_history | | Files | list_directory, query_directory_settings | | Sites | query_sites, query_site_userdata, test_site, update_site, update_site_cookie | | System | query_schedulers, run_scheduler, create_agent_task, query_agent_tasks, update_agent_task, run_agent_task, delete_agent_task, query_workflows, run_workflow, query_rule_groups, query_episode_schedule, send_message |

Workflows

Search and Download

1. Search TMDB

Search for a movie or TV show by title: `moviepilot tool run 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.

2. Search torrents

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: `moviepilot tool run query_sites`

Search torrents using default sites: `moviepilot tool run search_torrents tmdb_id=791373 media_type="movie"`

Search torrents using user-specified sites (pass site IDs from `query_sites`): `moviepilot tool run 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.

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

Run `moviepilot tool 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: `moviepilot tool run get_search_results resolution='1080p,2160p' free_state='免费,50%'`

To filter subtitle, audio, DIY, translation, or release notes that may appear outside the title, use `content_pattern`. It matches the torrent title, description, and labels while `title_pattern` continues to match the title only. Set `include_description=true` when the description is needed to explain why a result matched: `moviepilot tool run get_search_results content_pattern='特效字幕|国语|DIY' include_description=true`

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, `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小时`).

5. Check before down