moviepilot-cli

MoviePilot CLI

すべてのスクリプトパスは、このスキルファイルからの相対パスです。

ローカルの moviepilot tool ... コマンドを使用して、MoviePilot MCP ツールを操作します。 このコマンドはローカルの MoviePilot 設定を読み込むため、通常のローカル使用時に ユーザーに API_TOKEN、データベースのパスワード、バックエンドの DSN を尋ねないでください。

対象範囲と制限

このスキルは、MCP ツールとして公開されている通常の MoviePilot 製品操作を対象とします。 より的確に対応できる場合は、まず別のスキルを選択してください。

リクエスト	推奨スキル
スラッシュコマンドまたはプラグイン／システムコマンドのディスパッチ	command-dispatch
手動でのファイル整理	organize-files
失敗した転送履歴レコードの再試行	transfer-failed-retry
MCP ツールでは公開されていない REST エンドポイントへの直接アクセス	moviepilot-api
SQL クエリの直接実行またはデータベースの更新	database-operation
再起動、バージョン確認、アップグレード	moviepilot-update
ブラウザーのみで確認できる状態、サイトのログインページ、スクリーンショット、Cookie	browser-use

必要な操作に対応する MCP ツールがないことを moviepilot tool list と moviepilot tool show <command> で確認した後に限り、moviepilot-api を使用してください。 SQL による調査や変更が明示的に必要な場合、または製品ツール／API ではデータに関する 質問に回答できない場合に限り、database-operation を使用してください。

コマンドの確認

利用可能なコマンドをすべて一覧表示します：moviepilot tool list

特定のコマンドのパラメーターと使用方法を表示します：moviepilot tool show <command>

ツール一覧には、有効なプラグインが宣言しているツールも含まれます。プラグインを有効化、 無効化、再読み込み、または再設定した後は、コマンド選択に更新された実行時レジストリを 使用できるよう、tool list と tool show を再実行してください。

コマンドを実行する前に、必ず show <command> を実行してください。パラメーター名は推測できないため、当てずっぽうで指定しないでください。

コマンドグループ

カテゴリー	コマンド
メディア検索	search_media, recognize_media, query_media_detail, get_recommendations, search_person, search_person_credits
トレント	search_torrents, get_search_results
ダウンロード	add_download_tasks, query_download_tasks, update_download_tasks, delete_download_tasks, 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, 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

ワークフロー

メッセージの送信

送信する前に moviepilot tool show send_message を実行してください。Telegram で構造化された返信を送る場合は、 省略可能な rich_message 引数を優先し、完全な GitHub 形式の Markdown 本文を指定してください。見出し、リスト、表、 引用、コードブロック、リンクは Telegram Rich Message のコンテンツに変換されます。同じ内容を message、 title、image_url に重複して記載しないでください。Rich Message が不要な場合は、これらの通常のフィールドを使用します。 その他の設定済みチャンネルでは、Rich Markdown のソースがプレーンテキストのフォールバックとして送信されます。

検索とダウンロード

1. TMDB を検索する

タイトルで映画またはテレビ番組を検索します： moviepilot tool run search_media title="..." media_type="movie"

ユーザーがテレビ番組のシーズンを指定した場合は、まずシーズン検証の手順を実行してください。ユーザーが指定したシーズン番号は TMDB と一致しない場合があります。

2. トレントを検索する

search_media が返した media_source と media_id をそのまま再利用してください。選択された主識別子を、補助的な TMDB、Douban、Bangumi、または AniList のマッピング ID に置き換えないでください。

sites= を省略すると、ユーザーのデフォルトサイトが使用されます。ユーザーがサイトを指定した場合は、まずサイト ID を取得してください： moviepilot tool run query_sites

デフォルトサイトでトレントを検索する： moviepilot tool run search_torrents media_source="themoviedb" media_id=791373 media_type="movie"

ユーザー指定のサイトでトレントを検索する（query_sites のサイト ID を渡す）： moviepilot tool run search_torrents media_source="themoviedb" media_id=791373 media_type="movie" sites='1,3'

search_torrents が返されたら：

1. 停止してください。まだ get_search_results を呼び出さないでください。
2. すべての filter_options フィールドと、各フィールド内のすべての値をそのままユーザーに提示してください。
3. フィールドや値を事前に選択、要約、省略しないでください。
4. 次のステップに進む前に、ユーザーがフィルターを選択するか、フィルターが不要であることを確認するまで待ってください。

3. フィルター適用済みの結果を取得する（ユーザーが filter_options に応答した後のみ）

moviepilot tool show get_search_results を実行して、使用可能なパラメーターを確認してください。フィルターのロジック：同一フィールド内は OR、フィールド間は AND です。

フィルター値は search_torrents が返した filter_options の値を使用してください。独自に作成したり、翻訳、正規化したり、他のソースの値を使用したりしないでください。注：filter_options のキーは camelCase（例：freeState）ですが、get_search_results のパラメーターは snake_case（例：free_state）です。

選択したフィルターを使って結果を取得する： moviepilot tool run get_search_results resolution='1080p,2160p' free_state='免费,50%'

タイトル以外に表示される場合がある字幕、音声、DIY、翻訳、リリースノートでフィルターするには、content_pattern を使用してください。title_pattern がタイトルのみを照合するのに対し、これはトレントのタイトル、説明、ラベルを照合します。どの結果が一致したのかを説明するために説明が必要な場合は include_description=true を設定し、ラベルを返す必要がある場合は include_labels=true を設定してください： moviepilot tool run get_search_results content_pattern='特效字幕|国语|DIY' include_description=true include_labels=true

結果が空の場合は、どのフィルターを緩和するかをユーザーに伝え、再試行する前に確認してください。

4. 結果を番号付きリストで提示する

事前に選択せず、すべての結果を表示してください。各行には、インデックス、タイトル、サイズ、シーダー数、解像度、リリースグループ、volume_factor、freedate_diff を含めてください。

volume_factor	意味
免费	無料ダウンロード
50%	ダウンロードサイズが50%
2X	アップロード量が2倍
2X免费	アップロード量が2倍＋無料
普通	割引なし

freedate_diff：無料期間の残り時間（例：2天3小时）。

5. ダウンロード前に確認する

ユーザーがトレントを選択したら、ライブラリとサブスクリプションの確認ステップを実行してください。

メディアがすでにライブラリに存在する、またはサブスクライブ済みの場合は、停止して確認結果をユーザーに報告してください。

6. ダウンロードを追加する

1つ以上のトレントをダウンロードします（torrent_url は get_search_results の出力から取得します）： moviepilot tool run add_download_tasks torrent_url="abc1234:1,def5678:2"

エラー処理

ステップ	対応
search_media が空	別のタイトル（英語名／原題）で再試行し、それでも見つからない場合はタイトルまたは正確な media_source と media_id を尋ねてください。
search_torrents が空	ユーザーに伝え、異なるサイトで再試行するか確認してください。
get_search_results が空	フィルターを黙って広げないでください。緩和するフィルターを提案し、再試行する前に確認してください。
add_download_tasks が失敗	query_downloaders と query_download_tasks を実行して原因を調査し、ユーザーに報告してください。

サブスクリプションの追加

1. search_media を実行し、返された media_source と media_id のペアを保持します。
2. ライブラリとサブスクリプションの確認の手順を実行します。メディアがすでに存在するか、サブスクライブ済みの場合は、停止してユーザーに報告します。
3. ユーザーがテレビ番組のシーズンを指定した場合は、最初にシーズン検証の手順を実行します。

映画またはテレビ番組をサブスクライブします： moviepilot tool run add_subscribe title="..." year="2011" media_type="tv" media_source="themoviedb" media_id=42009

特定のシーズンをサブスクライブします： moviepilot tool run add_subscribe title="..." year="2011" media_type="tv" media_source="themoviedb" media_id=42009 season=4

特定のエピソードからサブスクライブします： moviepilot tool run add_subscribe title="..." year="2024" media_type="tv" media_source="themoviedb" media_id=12345 season=1 start_episode=13

ロスレス品質のアルバム全体をサブスクライブし、音質をアップグレードし続けます： moviepilot tool run add_subscribe title="..." media_type="music" music_type="album" media_source="musicbrainz" media_id="<release-group-id>" audio_quality="hires|lossless" audio_format="DSD|FLAC|ALAC" min_bit_depth=24 best_version=1

オーディオのビットレートとサンプルレートの値には、bps と Hz を使用します。たとえば、min_bitrate=320000 と min_sample_rate=96000 を指定します。

ダウンロードの管理

ダウンロードタスクを一覧表示し、後続の操作に使用するハッシュを取得します： moviepilot tool run query_download_tasks status=downloading

ダウンローダーでダウンロード中でも一時停止中でもないタスクには status=completed を使用します。MoviePilot タグが付いたダウンローダータスクをすべて含めるには、status=all を使用します。MoviePilot の組み込みタグが付いていないタスクを調査する場合は、include_all_tags=true を追加します。トラッカー URL が必要な場合は、include_trackers=true を追加するか、hash でクエリします。

ダウンロードタスクを更新します（ダウンローダーが対応している場合、開始／停止、タグ、速度制限、トラッカー、保存先、カテゴリ、比率、シード時間を設定できます）： moviepilot tool run update_download_tasks hash=<hash> action=stop upload_limit=512 download_limit=2048

ダウンロードタスクにトラッカーを追加します： moviepilot tool run update_download_tasks hash=<hash> trackers='https://tracker.example/announce,udp://tracker.example:80/announce'

ダウンロードタスクを削除します（取り消しできないため、先にユーザーに確認します）： moviepilot tool run delete_download_tasks hash=<hash>

ダウンロードタスクを削除し、ファイルも削除します（取り消しできないため、先にユーザーに確認します）： moviepilot tool run delete_download_tasks hash=<hash> delete_files=true

サブスクリプションの管理

有効なサブスクリプションを一覧表示します： moviepilot tool run query_subscribes status=R

サブスクリプションのフィルターを更新します： moviepilot tool run update_subscribe subscribe_id=123 resolution="1080p"

テレビ番組のベストバージョンのサブスクリプションで、シーズン全体のパックのみをダウンロードします： moviepilot tool run update_subscribe subscribe_id=123 best_version=1 best_version_full=1

未取得のエピソードの検索を開始します（先にユーザーに確認します）： moviepilot tool run search_subscribe subscribe_id=123

サブスクリプションを削除します（先にユーザーに確認します）： moviepilot tool run delete_subscribe subscribe_id=123

自律エージェントのタスクを管理する

自律タスクは、ユーザーが遅延実行、定期実行、リマインダー、または監視の動作を明示的に依頼した場合にのみ使用してください。即時の作業は直接実行してください。現地時刻には MoviePilot の TZ 設定を使用してください。

スケジュール実行では元のエージェントセッションのコンテキストが再利用されますが、ユーザー向けメッセージは、タスクを作成したチャンネルに紐づけられるのではなく、MoviePilot で設定された通知チャンネルを通じて配信されます。実行中にエージェントがメッセージツールで結果全体を送信した場合、実行完了時に同じ最終回答が再度送信されることはありません。

自律タスク用ツールでは、query_agent_tasks が返す整数の task_id を使用します。query_schedulers と run_scheduler は MoviePilot のシステム、プラグイン、ワークフローのランタイムサービス専用で、文字列の job_id を使用します。これらの ID を混同したり、自律タスクにこれらのツールを使用したりしないでください。

相対的な日時での単発依頼には、date と delay_minutes を使用してください。MoviePilot が正確な実行時刻を計算して保存します。 moviepilot tool run create_agent_task name="检查电影资源" content="搜索电影《示例电影》是否有资源并报告，不要自动下载。" trigger_type=date delay_minutes=30

固定時刻に実行する単発タスクには、ISO 8601 形式の trigger を指定して date を使用してください。 moviepilot tool run create_agent_task name="今晚检查资源" content="检查目标电影是否有资源并报告。" trigger_type=date trigger="2026-07-19 20:30:00"

定期的な作業には、標準の 5 フィールド Cron 式を使用してください。次の例は毎日 20:30 に実行されます。 moviepilot tool run create_agent_task name="每日资源检查" content="检查目标电影是否有资源并报告。" trigger_type=cron trigger="30 20 * * *"

タスクを一覧表示し、next_run_at と最新の結果を確認します。 moviepilot tool run query_agent_tasks

タスクを一時停止または再開します。 moviepilot tool run update_agent_task task_id=1 enabled=false

現在のエージェントターン内で待機せず、実行可能なタスクを直ちに実行キューに追加します。 moviepilot tool run run_agent_task task_id=1

ユーザーに恒久的な削除を確認してから、タスクを削除してください。 moviepilot tool run delete_agent_task task_id=1

ライブラリとサブスクリプションを確認する

重複を避けるため、ダウンロードやサブスクリプションの前に実行してください。

メディアがすでにライブラリに存在するか確認します。 moviepilot tool run query_library_exists media_source="themoviedb" media_id=123456 media_type="movie"

メディアがすでにサブスクリプション登録されているか確認します。 moviepilot tool run query_subscribes media_source="themoviedb" media_id=123456

シーズンの検証

ユーザーがシーズンを指定した場合は必ず実施してください。作品によっては、1 つの TMDB シーズンに複数のパートが収録されている一方、オンラインコミュニティやトレントサイトでは各パートが別々の「シーズン」として扱われることがあります。

1. シーズンが存在するか確認する

メディアの詳細を取得して、利用可能なシーズンを確認します。 moviepilot tool run query_media_detail media_source="themoviedb" media_id=<id> media_type="tv"

season_info とユーザーが指定したシーズンを比較します。

1. シーズンが season_info に存在する場合 → そのシーズン番号をそのまま使用し、呼び出し元のワークフローに戻ります。
2. シーズンが存在しない場合 → ユーザーの「シーズン」は、既存の TMDB シーズン内の後半のエピソード範囲に該当する可能性があります。season_info のうち最新（番号が最大）のシーズンを記録し、次のステップに進みます。

2. 正しいエピソード範囲を特定する

season_info にある最新シーズンのエピソード放送予定を取得します。これは TMDB 専用ツールのため、ネイティブの tmdb_id パラメーターを使用します。 moviepilot tool run query_episode_schedule tmdb_id=<id> season=<latest_season_number>

air_date を使って、ユーザーが欠けているシーズンと呼んでいる可能性のある、最近放送されたエピソードのまとまりを探します。エピソード間の air_date の空白に注目してください。この空白はパートの区切りを示し、その後のエピソードが、ユーザーの言う次の「シーズン」に当たる可能性があります。たとえば、TMDB のシーズン 1 にエピソード 1～24 があり、エピソード 12 と 13 の間に数か月の空白がある場合、エピソード 13～24 はユーザーが言う「シーズン 2」に相当します。そのような空白がない場合は、コンテンツを利用できないことをユーザーに伝えてください。それ以外の場合は、エピソード範囲をユーザーに確認してください。

エラー処理

設定がない場合、または認証に失敗した場合は、moviepilot doctor を実行して、ローカルの MoviePilot のインストール状態と設定を確認してください。プラグインのみのログで検出された問題は引き続き表示されますが、それだけで Doctor の全体的なステータスが下がることはありません。 ローカルの CLI を使用する際、API キーをプロンプトに貼り付けるようユーザーに求めないでください。