pp-hackernews

Hacker News — Printing Press CLI

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

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

1. Printing Press インストーラーを使ってインストールします。macOS/Linux ではデフォルトで $HOME/.local/bin に、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin にバイナリがインストールされます。

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

2. 確認します：hackernews-pp-cli --version
3. 報告されたインストールディレクトリが、このスキルを実行するエージェント／ランタイムの $PATH に含まれていることを確認してください。

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

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

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

この CLI を使用する場面

エージェントによる日次差分の確認、トピックの動向把握、採用スレッドの集約、投稿前の再投稿チェック、コンテキストウィンドウ用のスレッド要約など、HN の動向をプログラムで監視・分析する必要がある場合は、hackernews-pp-cli をご利用ください。ローカルストアにより、後続のクエリを低コストで実行でき、オフラインでも使いやすくなります。

この CLI を使用しない場面

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

独自の機能

この API を扱う他のツールでは、以下の機能を利用できません。

積み重なるローカルスナップショット

• since — 前回の同期以降に、フロントページで順位が上がったもの、下がったもの、登場したもの、表示されなくなったものを正確に確認できます。

  エージェントが毎日起動し、ポーリングのたびに500件のアイテムを再取得することなく、昨日からHNで何が変わったかを把握する必要がある場合にご利用ください。

  hackernews-pp-cli since --json
  

• controversial — 最近の期間におけるコメント数とポイント数の比率が最も高い順にストーリーを表示します。多くの人が議論を交わしている話題を確認できます。

  人気度だけでなく、エンゲージメントと支持の比率が高い、白熱した議論を示すストーリーを探したい場合にご利用ください。

  hackernews-pp-cli controversial --window 7d --json
  

• velocity — ローカルスナップショットをもとに、ストーリーの順位の推移を表示します。上昇、横ばい、下降を確認できます。

  エージェントから「このストーリーの勢いはまだ増しているのか、それとももうピークを過ぎたのか」と尋ねられた場合にご利用ください。意味のある回答を得るには、スナップショットが必要です。

  hackernews-pp-cli velocity 47998158 --json
  

• sync — top/new/best/show/ask/job のリストと最近変更されたアイテムをローカルの SQLite に取り込み、オフライン利用とスナップショット履歴の保存を可能にします。

  1日に1回（エージェントの場合は1時間に1回）実行してください。これにより、実現不可能だった since/velocity/controversial/users-stats のクエリを、1つの SQL クエリで実行できるようになります。

  hackernews-pp-cli sync --resources updates --agent
  

Algolia の活用

• pulse — 任意のトピックについて、直近N日間の日別の言及数、平均スコア、コメント数を確認できます。

  「今のトップストーリーは何か」ではなく、「このトピックは盛り上がっているのか、落ち着いてきているのか」を知りたい場合にご利用ください。

  hackernews-pp-cli pulse rust --days 7 --agent
  

• repost — この URL は以前に投稿されたことがあるかを確認できます。過去の投稿をすべて、スコア、コメント数、日付とともに一覧表示します。

  Show HN を投稿する前にご利用ください。重複した URL の投稿はすぐに反応がなくなります。まず過去の投稿がどうだったかを確認しましょう。

  hackernews-pp-cli repost https://example.com/article
  

• search local — これまでに同期したすべてのストーリーとコメントを対象に、オフラインで全文検索できます。使うほどコーパスが増えていきます。

  ニッチなトピックを調査したり、前四半期の調査を振り返ったりする場合にご利用ください。Algolia では順位が下がったり、検索結果から外れたりする可能性がありますが、ローカルコーパスからは失われません。

  hackernews-pp-cli search local "vector database" --limit 20 --json
  

採用スレッドの分析

• hiring stats — 直近 N か月分の「Who is Hiring」スレッドを集計します。人気の言語、リモート勤務の割合、人気企業、地域別の分布を確認できます。

  四半期または季節ごとの採用傾向、たとえば言語の人気度、リモート勤務の割合の変化、地域ごとの求人密度を知りたい場合に使います。今月の求人情報だけを調べる場合には向きません。

  hackernews-pp-cli hiring stats --months 3 --agent
  

• hiring companies — 直近 N 件の採用スレッドのうち M 件に投稿した企業を、初出時期、最終出現時期、投稿月数とともに表示します。

  採用候補の調査や傾向の追跡に使います。HNHIRING.com をスクレイピングせずに、継続的に採用している企業と、一度だけ投稿した企業を把握できます。

  hackernews-pp-cli hiring companies --months 6 --min-posts 3 --agent
  

エンティティを横断するローカルクエリ

• users stats — ユーザーの投稿におけるスコアの中央値と p90 に加え、反響の規模別分類と時間帯別のスコア分布を表示します。

  自分の投稿に対する反響の傾向を知るために、投稿前に使えます。また、交流する前に投稿者の過去の活動を把握する場合にも使えます。

  hackernews-pp-cli users stats pg --json
  

コマンドリファレンス

items — ID を指定して HN のアイテム（ストーリー、コメント、求人、投票）を取得します

• hackernews-pp-cli items <itemId> — 特定のストーリー、コメント、求人、投票の詳細を取得します

maxitem — 現在の最大アイテム ID

• hackernews-pp-cli maxitem — Hacker News で現在割り当てられている最大のアイテム ID を返します

stories — Hacker News のトップ、新着、ベストストーリーを閲覧します

• hackernews-pp-cli stories ask — 最新の Ask HN 投稿を取得します
• hackernews-pp-cli stories best — Hacker News で最も多くの票を集めたストーリーを取得します
• hackernews-pp-cli stories job — Hacker News の最新求人情報を取得します
• hackernews-pp-cli stories new — Hacker News の最新ストーリーを取得します
• hackernews-pp-cli stories show — 最新の Show HN 投稿を取得します
• hackernews-pp-cli stories top — Hacker News の現在のトップストーリーを取得します

updates — 最近変更されたアイテムとプロフィール

• hackernews-pp-cli updates — 最近変更されたアイテムとユーザープロフィールを表示します

users — Hacker News のユーザープロフィールを検索します

• hackernews-pp-cli users <userId> — カルマや投稿履歴など、ユーザーのプロフィールを取得します

手書きコマンド

• hackernews-pp-cli sync — トップ、新着、ベスト、Show、Ask、求人の各リストと最近のアイテムをローカルの SQLite ストアに取り込みます
• hackernews-pp-cli search <query> — Algolia を使って Hacker News のストーリーとコメントを全文検索します（オフラインの FTS には 'search local' を使います）
• hackernews-pp-cli hiring — 「Ask HN: Who is hiring」スレッドを分析します（絞り込み、統計、企業）
• hackernews-pp-cli freelance — 「Ask HN: Freelancer? Seeking freelancer?」スレッドを分析します（絞り込み）
• hackernews-pp-cli since — 前回の同期以降にフロントページで変更された内容を表示します（追加、削除、移動したストーリー）
• hackernews-pp-cli pulse <topic> — トピックについて HN で話題になっている内容を表示します（日ごとの言及数、スコア、コメント数）
• hackernews-pp-cli controversial — コメント数とポイント数の比率が最も高いストーリーを見つけます（意見が分かれる議論）
• hackernews-pp-cli repost <url> — この URL が HN に投稿されたことがあるかを確認します。過去の投稿をスコアと日付とともに一覧表示します
• hackernews-pp-cli velocity <id> — ローカルスナップショットにおけるストーリーの順位の推移を表示します
• hackernews-pp-cli doctor — API への接続、ストアへの書き込み、設定の妥当性を自己診断します

Freshness Contract

この出力用 CLI が最新性を一定の範囲で管理するのは、登録済みのストアを利用した読み取りコマンドのパスのみです。--data-source auto モードでは、これらのパスは sync_state を確認し、ローカルデータを読み取る前に範囲を限定した更新を実行する場合があります。--data-source local は更新を実行しません。--data-source live は API を読み取り、ローカルストアを変更しません。ソースの選択を変更せずに最新性チェックをスキップするには、HACKERNEWS_NO_AUTO_REFRESH=1 を設定します。

対象となるパス：

• hackernews-pp-cli stories
• hackernews-pp-cli stories ask
• hackernews-pp-cli stories best
• hackernews-pp-cli stories job
• hackernews-pp-cli stories new
• hackernews-pp-cli stories show
• hackernews-pp-cli stories top
• hackernews-pp-cli updates

JSON 出力で生成されたプロヴェナンスエンベロープを使用する場合、最新性メタデータは meta.freshness に表示されます。これは対象となるコマンドパスの現在のキャッシュの最新性を示すものであり、履歴データの完全なバックフィルや、API 固有のデータ拡充を保証するものではありません。

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

やりたいことは分かっていても、どのコマンドを使うか分からない場合は、CLI に直接尋ねてください。

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

which は、自然言語での機能に関する問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 件の一致があることを示し、終了コード 2 は確信の持てる一致がないことを示します。その場合は --help を使うか、より範囲を絞った問い合わせをしてください。

レシピ

エージェント向け、日次のフロントページ差分

hackernews-pp-cli sync && hackernews-pp-cli since --json --select added,removed,moved

同期してから差分を取得します。--select によってペイロードが変更差分だけに絞られるため、エージェントが処理するデータは数メガバイトではなく数キロバイトになります。

選択したフィールドによるトピック監視

hackernews-pp-cli pulse openai --days 7 --agent --select buckets.day,buckets.hits,buckets.avg_score

日ごとの言及数、平均スコア、コメント数を集計します。--select を使って、深くネストされたレスポンスからトレンドの軸となる項目だけを取得します。

投稿前の重複チェック

hackernews-pp-cli repost https://example.com/article --json

その URL の過去の投稿をすべて、スコア、コメント数、日付とともに一覧表示します。「これはすでに投稿されているか」という疑問に、1 回の往復で回答します。

リモートの Go 職を「Who's Hiring」から絞り込む

hackernews-pp-cli hiring filter "(remote|REMOTE).*\\bGo\\b" --json

最新の月次スレッドに対して正規表現を実行します。二重にエスケープされた \b は実際の正規表現の単語境界です。--json を指定すると、1 つの大きな一致結果ではなく、構造化された行が得られます。

四半期ごとの採用トレンド

hackernews-pp-cli hiring companies --months 6 --min-posts 3 --agent

過去 6 回の月次スレッドのうち 3 回以上に投稿している企業を、初出、最終出、投稿月数とともに表示します。ローカルストアなしでは実行できない月をまたぐクエリです。

認証の設定

認証は不要です。

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

エージェントモード

任意のコマンドに --agent を追加します。次のオプションが有効になります：--json --compact --no-input --no-color --yes。

• パイプ対応 — stdout に JSON、stderr にエラーを出力します

• フィルター可能 — --select でフィールドの一部を保持します。ドット区切りのパスはネストされた構造をたどり、配列は各要素をたどります。詳細な API でコンテキストを小さく保つうえで重要です：

  hackernews-pp-cli items 47998158 --agent --select id,name,status
  

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

• オフラインに対応 — 同期／検索コマンドは、利用可能な場合、ローカルの SQLite ストアを使用できます

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

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

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力をプロヴェナンスエンベロープでラップします。

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

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

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

あなた（またはエージェント）がこの CLI に違和感を覚えたら、記録してください。

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

エントリはローカルの ~/.hackernews-pp-cli/feedback.jsonl に保存されます。HACKERNEWS_FEEDBACK_ENDPOINT が設定され、かつ --send が渡されるか HACKERNEWS_FEEDBACK_AUTO_SEND=true が設定されない限り、POST されることはありません。デフォルトの動作はローカルのみです。

バグ報告ではなく、意外に感じたことを書いてください。短く、具体的に、1 行で。それが積み重なっていく要素です。

出力の配信

すべてのコマンドは --deliver <sink> を受け付けます。出力は標準出力に加えて（または標準出力の代わりに）指定したシンクに送られるため、エージェントはコマンド結果を手作業でパイプに渡さずにルーティングできます。次の 3 つのシンクに対応しています。

シンク	効果
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイル + リネーム）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

サポート対象外のスキームは、サポート対象のセットを示す構造化エラーで拒否されます。Webhook の失敗時はゼロ以外の終了コードを返し、URL と HTTP ステータスを標準エラー出力に記録します。

名前付きプロファイル

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

hackernews-pp-cli profile save briefing --json
hackernews-pp-cli --profile briefing items 47998158
hackernews-pp-cli profile list --json
hackernews-pp-cli profile show briefing
hackernews-pp-cli profile delete briefing --yes

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

終了コード

コード	意味
0	成功
2	使用エラー（引数が不正です）
3	リソースが見つかりません
5	API エラー（上流の問題）
7	レート制限。待機して再試行してください
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → hackernews-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/hackernews/cmd/hackernews-pp-mcp@latest
   

2. Claude Code に登録します。

   claude mcp add hackernews-pp-mcp -- hackernews-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

   hackernews-pp-cli <command> [subcommand] [args] --agent
   

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