pp-movie-goat

Movie Goat — Printing Press CLI

前提条件：CLI をインストールする

このスキルは movie-goat-pp-cli バイナリを使用します。**このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。**見つからない場合は、先にインストールしてください。

1. Printing Press インストーラーを使用してインストールします。バイナリのインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin が既定です。

   npx -y @mvanhorn/printing-press-library install movie-goat --cli-only
   

2. 次のコマンドで確認します：movie-goat-pp-cli --version
3. 表示されたインストール先が、このスキルを実行するエージェント／ランタイムの $PATH に含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go による直接インストールに切り替えてください（Go 1.26.6 以降が必要です）。

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/movie-goat/cmd/movie-goat-pp-cli@latest

インストール後に --version で「command not found」と表示される場合、ランタイムからバイナリのディレクトリを $PATH 経由で参照できていません。確認が成功するまで、スキルのコマンドを実行しないでください。

この CLI を使用する場合

ストリーミング配信状況と複数の情報源の評価を組み合わせて回答する必要がある、映画通向けの質問には Movie Goat を使用してください。今夜観る作品の選定、シリーズ作品の一気見計画、評価付きのキャリア年表といった用途に適しています。興行収入の追跡、レビューの感情分析、あらすじやレビューの LLM 風要約が必要なワークフローには適していません。

この CLI を使用しない場合

作成、更新、削除、公開、コメント、賛成票の投票、招待、注文、メッセージ送信、予約、購入、リモート状態の変更が必要なリクエストには、この CLI を有効化しないでください。この Printing Press CLI が提供するのは、確認、エクスポート、同期、分析のための読み取り専用コマンドです。

独自の機能

これらの機能は、この API の他のツールでは利用できません。

映画通のためのお決まりの楽しみ方

• tonight — 実際に利用中のサービスで配信されている、トレンド作品の中から今夜観る作品を選びます。

  配信状況で絞り込んだ候補リストが必要な場合に使用します。1 回の呼び出しで、TMDb／RT／JustWatch のタブを行き来する手間を省けます。

  movie-goat-pp-cli tonight --mood thriller --max-runtime 120 --providers netflix,max --region US --json
  

• ratings — あらゆる作品の TMDb、IMDb、Rotten Tomatoes、Metacritic の評価を 1 枚のカードにまとめます。

  作品の複数の情報源に基づく標準的な評価が必要な場合に使用します。OMDB_API_KEY が設定されていない場合は、TMDb のみを使った結果に適切に切り替わります。

  movie-goat-pp-cli ratings 550 --json
  

• リメイクを考慮した作品名の解決 — TMDb ID の代わりに作品名を受け取るすべてのコマンドは、同じ作品名が複数ある場合、その旨を明示します。

  TMDb の検索では独自の関連度スコアに基づいて順位が付けられるため、「Sabrina」は、1954 年の Wilder によるオリジナル版の評価がより高い場合でも、1995 年のリメイク版に解決されます。評価の高い候補が複数ある作品では、CLI はその情報を両方の出力経路で報告します。stderr には人間向けの通知を、stdout の JSON には、stderr を読まない利用者向けの meta.ambiguous レコードを出力します。--year、"Title (YYYY)" 形式の接尾辞、または ID を指定して、目的の作品を明示してください。

  movie-goat-pp-cli ratings "Sabrina" --year 1954 --json
  

• marathon — 視聴順、合計上映時間、休憩の提案を含む、シリーズ作品の一気見計画を立てます。

  イベントでの視聴を計画する際に使用します。エージェントはスケジュールを出力して、グループと共有できます。

  movie-goat-pp-cli marathon "The Avengers" --order release --breaks-every 240 --json
  

• career — 俳優や監督の全フィルモグラフィーを、評価と時系列で調べます。

  評価付きの時系列フィルモグラフィーが必要な場合に使用します。情報源をまたいだ評価で、IMDb の単純な一覧を置き換えます。

  movie-goat-pp-cli career "Christopher Nolan" --since 2010 --role director --json
  

• versus — 2 本の映画または番組を、評価、キャスト、上映時間、配信状況の面から並べて比較します。

  最終候補 2 本から選ぶ必要がある場合に使用します。1 つのコマンドで、あらゆる観点から両者の違いを確認できます。

  movie-goat-pp-cli versus 550 27205 --region US --json
  

• collaborators — ある人物のクレジットに 2 回以上登場する人物を、回数と作品名とともに一覧表示します。

  映画制作者の人脈を調べる際に使用します。繰り返し参加している撮影監督／作曲家／俳優を機械的に抽出します。

  movie-goat-pp-cli collaborators "Christopher Nolan" --min-count 3 --role crew --json
  

積み重なるローカル状態

• watchlist list — ローカルの SQLite ウォッチリストです。利用中のサービスでストリーミング視聴できるタイトルにフラグを付けます。

  保存したリストからストリーミング視聴できるタイトルを見つけるため、毎週使用します。タイトルごとに JustWatch をその都度確認する手間を省きます。

  movie-goat-pp-cli watchlist list --available --providers netflix,max --region US --json
  

• queue — ウォッチリストのおすすめと類似タイトルをもとに、次に観る作品を提案します。

  保存した関心事をもとに新しいキューが必要な場合に使用します。ローカル状態と API のおすすめを組み合わせます。

  movie-goat-pp-cli queue --limit 20 --providers netflix,max --region US --json
  

コマンドリファレンス

auth — TMDB_API_KEY と OMDB_API_KEY の認証情報を管理します

• movie-goat-pp-cli auth status — TMDb と OMDb の両方の認証情報のステータスを表示します
• movie-goat-pp-cli auth set-token — TMDb API トークンを設定ファイルに保存します
• movie-goat-pp-cli auth set-omdb-token — 任意の OMDb API トークンを設定ファイルに保存します
• movie-goat-pp-cli auth logout — 保存された認証情報を消去します

discover — 詳細なフィルターを使って映画やテレビ番組を探します

• movie-goat-pp-cli discover movies — ジャンル、年、評価、レーティング、キャスト、スタッフ、配信プロバイダーなどで映画を探します
• movie-goat-pp-cli discover tv — ジャンル、年、評価、ネットワーク、配信プロバイダーでテレビ番組を探します

genres — 映画とテレビ番組のジャンル一覧を取得します

• movie-goat-pp-cli genres movies — 映画のジャンル一覧を取得します
• movie-goat-pp-cli genres tv — テレビ番組のジャンル一覧を取得します

movies — 映画を検索して閲覧します

• movie-goat-pp-cli movies get — キャスト、評価、ストリーミング配信状況など、映画の詳細情報を取得します
• movie-goat-pp-cli movies now-playing — 現在劇場公開中の映画を取得します
• movie-goat-pp-cli movies popular — 現在人気の映画を取得します
• movie-goat-pp-cli movies search — タイトルで映画を検索します
• movie-goat-pp-cli movies top-rated — 評価の高い映画を取得します
• movie-goat-pp-cli movies upcoming — まもなく劇場公開される映画を取得します

multi — 映画、テレビ番組、人物を横断して検索します

• movie-goat-pp-cli multi <query> — 1 回のクエリで映画、テレビ番組、人物を検索します

people — 人物（俳優、監督、スタッフ）を検索して閲覧します

• movie-goat-pp-cli people get — フィルモグラフィーを含む人物の詳細情報を取得します
• movie-goat-pp-cli people popular — エンターテインメント分野で人気の人物を取得します
• movie-goat-pp-cli people search — 名前で人物を検索します

trending — トレンドの映画、テレビ番組、人物を取得します

• movie-goat-pp-cli trending all — トレンドの映画、テレビ番組、人物を取得します
• movie-goat-pp-cli trending movies — トレンドの映画を取得します
• movie-goat-pp-cli trending people — トレンドの人物を取得します
• movie-goat-pp-cli trending tv — トレンドのテレビ番組を取得します

tv — テレビ番組を検索して閲覧します

• movie-goat-pp-cli tv airing-today — 今日エピソードが放送されるテレビ番組を取得します
• movie-goat-pp-cli tv get — テレビ番組の詳細情報を取得します
• movie-goat-pp-cli tv on-the-air — 現在放送中のテレビ番組を取得します
• movie-goat-pp-cli tv popular — 現在人気のテレビ番組を取得します
• movie-goat-pp-cli tv search — タイトルでテレビ番組を検索します
• movie-goat-pp-cli tv top-rated — 評価の高いテレビ番組を取得します

適切なコマンドを見つける

実行したいことは分かっているものの、どのコマンドを使えばよいか分からない場合は、CLI に直接問い合わせてください。

movie-goat-pp-cli which "<capability in your own words>"

which は、自然言語で記述された機能のクエリを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は 1 つ以上の候補が見つかったことを示し、終了コード 2 は確実な候補が見つからなかったことを示します。その場合は --help を使うか、より絞り込んだクエリを使用してください。

レシピ

今夜、評価が高く、利用中のサービスで視聴できる作品

movie-goat-pp-cli tonight --mood drama --max-runtime 130 --providers netflix,max,prime --region US --agent --select "results.title,results.year,results.rating,results.providers"

エージェントが判断に必要とする重要なフィールドだけを含む、ストリーミング配信で絞り込んだ候補リストです。

ウォッチリストの確認

movie-goat-pp-cli watchlist list --available --providers netflix,max --region US --agent

毎週の確認：保存したタイトルのうち、利用中のサービスでストリーミング視聴できるようになったものを調べます。

評価付きのキャリア深掘り

movie-goat-pp-cli career "Lynne Ramsay" --role director --agent --select "credits.title,credits.year,credits.rating_imdb,credits.rating_rt"

エージェント向けに範囲を絞った時系列のフィルモグラフィーと、重要な複数ソースの評価項目を確認できます。

ファイナリスト2作品を比較する

movie-goat-pp-cli versus 27205 87108 --region US --agent

『インセプション』と『TENET テネット』を並べて比較するカードです。評価、上映時間、出演者の重複、配信サービスを表示します。

シェル環境を変更せずに両方のAPIキーを保存する

movie-goat-pp-cli auth set-token YOUR_TMDB_API_KEY
movie-goat-pp-cli auth set-omdb-token YOUR_OMDB_API_KEY
movie-goat-pp-cli auth status --agent

両方の認証情報を ~/.config/movie-goat-pp-cli/config.toml（モード 0600）に書き込むため、環境変数を設定したプロセスだけでなく、マシン上のすべてのエージェントとシェルから利用できます。auth status は authenticated、omdb_configured、omdb_source を報告するため、エージェントは ratings を実行する前に、IMDb／RT／Metacritic の列に値が表示されるかどうかを確認できます。

リメイクではなくオリジナルを指定する

movie-goat-pp-cli ratings "Sabrina" --year 1954 --agent
movie-goat-pp-cli ratings "Sabrina (1954)" --agent
movie-goat-pp-cli versus "Sabrina (1954)" "Sabrina (1995)" --agent

ratings、marathon、watchlist add は --year を受け取ります。2つの位置引数を取る versus を含む、タイトルを受け取るすべてのコマンドでは、インラインの "Title (YYYY)" という形式も使えます。どちらも指定しない場合、CLI は引き続き TMDb の最上位の検索結果を選びますが、候補となる別の ID を stderr に出力します。

warn: "Sabrina" matches 3 titles on TMDb; using id 11860 — Sabrina (1995).
      TMDb's search relevance put it first, but Sabrina (1954) has more ratings (1373 vs 703).
      Other matches:
        6620  Sabrina (1954)
        503902  Sabrina (2018)
      Disambiguate with --year <YYYY>, a "title (YYYY)" suffix, or the TMDb id.

/search/* の検索結果は、TMDb が公開していない関連度スコアで並べられます。これは投票数でも popularity フィールドでもありません。今回のケースでは、1954年の作品が両方の値で上回っています（評価数は1373対703、人気度は4.25対3.60）が、検索結果では2番目に返されます。そのため、最上位の結果が定番の版と異なることがあり、通知では投票数を比較します。確認できるランキング要素はこれだけだからです。

評価のない、同名の珍しい作品では通知されないため、ratings "Inception" は何も表示しません。

stderr を読み取らないスクリプトでも検知できます。 同じイベントは JSON レスポンスの meta.ambiguous にも記録されます。そのため、cron ジョブや 2>/dev/null を付けて実行するパイプラインでも検知できます。誰も監視していないときこそ、誤った年を選ぶ危険性が最も高くなります。

movie-goat-pp-cli ratings "Sabrina" --agent 2>/dev/null | jq '.meta.ambiguous'

[
  {
    "query": "Sabrina",
    "kind": "titles",
    "match_count": 3,
    "signal": "alternative_better_rated",
    "chosen":  { "tmdb_id": 11860, "title": "Sabrina", "year": "1995", "vote_count": 703 },
    "alternatives": [
      { "tmdb_id": 6620,   "title": "Sabrina", "year": "1954", "vote_count": 1373 },
      { "tmdb_id": 503902, "title": "Sabrina", "year": "2018", "vote_count": 194 }
    ],
    "hint": "Disambiguate with --year <YYYY>, a \"title (YYYY)\" suffix, or the TMDb id."
  }
]

TMDb の検索で最上位にランクされた作品が最も高評価の作品ではない場合、signal は alternative_better_rated です。この場合は「停止して ID を指定する」必要があります。最上位の候補が最も高評価でもある場合は、multiple_exact_matches です。1つのコマンドで複数のタイトルを解決することがあるため（versus は2つを解決します）、meta.ambiguous はリストです。

popularity は TMDb のトレンドスコアで、報告された値がそのまま渡されます。これは検索結果の順序ではなく、シグナルが比較する値でもありません。シグナルが比較するのは vote_count です。

知っておくべきルール：

• 追加のみ。 このフィールドは stderr の通知が出る場合にのみ表示されます。曖昧さのない検索結果には meta キー自体が含まれないため、既存のパーサーには影響しません。
• --select で除外できません。 曖昧な検索結果では、--select title,ratings を指定しても meta.ambiguous が返されます。フィールドの一覧を絞り込むことは、そうしなければこの情報を見落とす習慣そのものだからです。
• --compact／--agent でも保持されます。 コンパクト出力の許可リストが適用されるのは配列です。これらのレスポンスはオブジェクトであり、コンパクト化ではブロックリストが使われるため、meta はそのまま残ります。
• --quiet は stderr の通知を抑制しますが、記録は抑制しません。 これらは別々の対象に向けた、独立した出力経路です。なお、これらのコマンドでは --quiet を指定すると stdout も完全に抑制されます（従来からの動作です）。このフィールドを読み取るには、--quiet を付けずに --json を使用してください。

シリーズ作品で映画鑑賞の夜を計画する

movie-goat-pp-cli marathon "Mission: Impossible" --order release --breaks-every 240 --agent

合計上映時間と休憩の提案を含む、順序付きのウォッチリストです。

認証の設定

Movie Goat は 2 つの API キーを使用し、それぞれを設定ファイルまたは環境変数に保存できます。

キー	必須	設定ファイルへの保存	環境変数
TMDb v3（無料、https://www.themoviedb.org/settings/api）	はい	movie-goat-pp-cli auth set-token <token>	TMDB_API_KEY
OMDb（無料、http://www.omdbapi.com/apikey.aspx）	いいえ	movie-goat-pp-cli auth set-omdb-token <token>	OMDB_API_KEY

両方のキーは、~/.config/movie-goat-pp-cli/config.toml（モード 0600）に、それぞれ api_key と omdb_api_key として保存されます。どちらのキーも、環境変数の値が保存済みの値より優先されるため、環境変数を使った既存の設定はそのまま機能します。

TMDb キーは Bearer ヘッダーではなく、クエリパラメーターとして送信されます。OMDb キーがない場合、ratings、versus、career は TMDb の情報のみを表示し、IMDb／RT／Metacritic の列は適切に省略されます。

movie-goat-pp-cli auth status では、両方の認証情報と、それぞれの取得元を確認できます。movie-goat-pp-cli auth logout を実行すると、設定ファイルから両方のキーが削除されます。

movie-goat-pp-cli doctor を実行して、設定を確認してください。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションが適用されます：--json --compact --no-input --no-color --yes。

• パイプ可能 — stdout には JSON、stderr にはエラーを出力します

• フィルター可能 — --select でフィールドを絞り込めます。ドット区切りのパスでネストした構造をたどり、配列内の要素にも適用されます。出力量の多い API でコンテキストを小さく保つために重要です：

  movie-goat-pp-cli movies get mock-value --agent --select id,name,status
  

• プレビュー可能 — --dry-run で、リクエストを送信せずに内容を表示します

• オフラインでも使いやすい — sync／search コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトは表示せず、すべての入力をフラグで指定します

• 読み取り専用 — 作成、更新、削除、公開、コメント、賛成票、招待、注文、送信、その他のデータを変更するリクエストには、この CLI を使用しないでください

レスポンスのエンベロープ

ローカルストアまたは API からデータを読み取るコマンドは、出力をデータの由来を示すエンベロープで囲みます：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を解析し、ライブデータかローカルデータかを確認するには .meta.source を参照してください。人が読める N results (live) の概要は、stdout が端末の場合にのみ stderr に出力されます。パイプやエージェントを使う場合、stdout には純粋な JSON が出力されます。

エージェントからのフィードバック

あなた（またはエージェント）がこの CLI に問題があると気づいたら、記録してください：

movie-goat-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
movie-goat-pp-cli feedback --stdin < notes.txt
movie-goat-pp-cli feedback list --json --limit 10

記録は ~/.movie-goat-pp-cli/feedback.jsonl にローカル保存されます。MOVIE_GOAT_FEEDBACK_ENDPOINT が設定されていて、さらに --send が指定されているか、MOVIE_GOAT_FEEDBACK_AUTO_SEND=true の場合を除き、POST されることはありません。デフォルトではローカルにのみ保存されます。

バグ報告ではなく、意外に感じたことを書いてください。短く、具体的に、一行で記述します。そうした記録が積み重なっていきます。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は stdout に加えて（または stdout の代わりに）、指定した出力先に送られるため、エージェントは手動でパイプをつながずにコマンドの結果を振り分けられます。次の 3 つの出力先に対応しています：

出力先	動作
stdout	デフォルト。stdout のみに出力します
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイルを作成してからリネーム）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

未対応のスキームは、対応する出力先を示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードを返し、URL と HTTP ステータスを stderr に記録します。

名前付きプロファイル

プロファイルとは、保存したフラグ値のセットで、複数回の実行にわたって再利用できます。スケジュールされたエージェントが、同じ設定で毎回同じコマンドを呼び出す場合に使用します。これは HeyGen の「Beacon」パターンです。

movie-goat-pp-cli profile save briefing --json
movie-goat-pp-cli --profile briefing movies get mock-value
movie-goat-pp-cli profile list --json
movie-goat-pp-cli profile show briefing
movie-goat-pp-cli profile delete briefing --yes

明示的に指定したフラグは、常にプロファイルの値より優先されます。プロファイルの値はデフォルト値より優先されます。agent-context は、すべての利用可能なプロファイルを available_profiles の下に一覧表示するため、情報を参照するエージェントは実行時にプロファイルを検出できます。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が誤っています）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します：

1. 空、help、または --help → movie-goat-pp-cli --help の出力を表示します
2. install で始まる場合 → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の前提条件を参照します
3. その他の場合 → 直接使用（--agent を付けて CLI コマンドとして実行します）

MCP サーバーのインストール

1. MCP サーバーをインストールします：

   go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/movie-goat/cmd/movie-goat-pp-mcp@latest
   

2. Claude Code に登録します：

   claude mcp add -e TMDB_API_KEY=<your-tmdb-key> -e OMDB_API_KEY=<your-omdb-key> movie-goat-pp-mcp -- movie-goat-pp-mcp
   

   OMDB_API_KEY は任意ですが、設定すると ratings、versus、career で IMDb、Rotten Tomatoes、Metacritic の情報を取得できます。
3. 確認します：claude mcp list

直接使用

1. インストール済みか確認します：which movie-goat-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある前提条件を参照してください）。
2. ユーザーのクエリに最適なコマンドを、上記の「独自の機能」と「コマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します：

   movie-goat-pp-cli <command> [subcommand] [args] --agent
   

4. 曖昧な場合は、サブコマンドのヘルプを確認します：movie-goat-pp-cli <command> --help。