pplx-cli

pplx - Perplexity のウェブ検索とページ抜粋 CLI

このスキルでできること

Perplexity の公開 pplx CLI をインストール、認証し、操作します。pplx search web はリアルタイムのウェブ検索、pplx content snippets はクエリに関連するページの抜粋を取得します。 出力の仕様：成功時は終了コード 0 で、標準出力に JSON オブジェクトをちょうど 1 つ出力します。失敗については落とし穴 4 を参照してください。

インストール

pplx --version がすでに動作する場合（2026.07.30.1785394496+1b7382b のような calver が表示されます）は、インストールをスキップしてください。

curl -fsSL https://github.com/perplexityai/perplexity-cli/releases/latest/download/install.sh | sh

SHA-256 検証済みで、sudo は不要です。~/.local/bin/pplx にインストールされます（上書きする場合：PPLX_INSTALL_PATH）。~/.local/bin が PATH に含まれていることを確認してください。 対応プラットフォーム：macOS arm64、Linux x86_64、Linux arm64 のみ。 pplx update で更新できます（チェックサムを検証してインプレースで置き換えます。API キーは不要です）。pplx update --check は新しいリリースがあるかどうかだけを報告します。

認証

まだ認証していない場合は、pplx auth login を実行して認証します（対話形式で、ターミナルが必要です。API キー：https://www.perplexity.ai/account/api）。 非対話型セッション（エージェント、CI）では、代わりに PERPLEXITY_API_KEY をエクスポートしてください。auth login はパイプ入力を拒否します（落とし穴 1）。

環境変数は、対話型の pplx auth login で保存したキー（<config>/perplexity/credentials.json。macOS では ~/Library/Application Support、Linux では $XDG_CONFIG_HOME または ~/.config）より優先されます。 キーが設定されていない場合、最初の実際のコマンドで AUTHENTICATION エラーが発生します。 CLI のすべての出力ではキーがマスキングされます。CLI は https://api.perplexity.ai と通信します。

検索

pplx search web "kubernetes pod OOMKilled causes"

標準出力：{hits: [{url, title, domain, snippet?, ...}], total, saved_to?}。 トークン数を抑えるには、保存してプレビューしてください。追加の位置引数は、同じ質問を別の表現にしたものです（落とし穴 3）。

pplx search web "kubernetes pod OOMKilled causes" "why does k8s keep killing my pod with OOMKilled" \
  -n 5 --output-dir out --stdout-preview=200

これにより、標準出力は数 KB に抑えられます。saved_to（実際にフィールドが切り詰められた場合は truncated も含みます）と、完全な JSON が out/web/{rand}.json に保存されます（リクエスト成功後にのみ書き込まれます）。プレビューだけでは不十分な場合は、ファイルを読んでください。 PPLX_OUTPUT_DIR を一度設定すると、--output-dir を繰り返し指定しなくても、すべてのコマンドでワークスペースに適したパスをデフォルトの保存先にできます。 その他の絞り込みフラグ（--domains、日付範囲、--recency-filter、--country、トークン予算）については、pplx search web --help を参照してください。

抜粋

pplx content snippets "<query>" <url>... [--max-tokens N] [--max-tokens-per-page N]

http(s) URL を 1～50 個指定できます。ここでの追加の位置引数は、抜粋する追加ページです。クエリの別表現ではありません（search web とは逆です。落とし穴 3）。 標準出力：{results: [{url, text?, tokens_count?, error?}], saved_to?}（URL ごとに結果が 1 つ）。 text を信頼する前に、すべての結果の error を確認してください。終了コード 0 はリクエストが成功したことを示すだけで、すべての URL の処理が成功したとは限りません（落とし穴 7）。URL の処理に失敗した場合は error が設定され、text はありません。 text 内の省略箇所は … で示されます。 トークン予算：--max-tokens はすべての抜粋の合計で、1～16384、デフォルトは 4096 です。--max-tokens-per-page はページごとで、1～4096 の範囲で --max-tokens 以下にする必要があります。デフォルトは min(1024, max_tokens) です。 保存ファイル：{dir}/snippets/{rand}.json。 クエリは位置引数のみです。-q／--query と --no-cache は、ここでは UNKNOWN_ARGUMENT の解析エラーになります。 v0.2.2 以前のバイナリでは、content snippets が不明なコマンドとしてエラーになります。先に pplx update を実行してください。 content fetch は削除されました。content snippets を使用してください。

不明な場合

各サブコマンドの --help には、すべてのフラグの説明に加えて、入力形式、標準出力の形式、保存ファイルのスキーマ、使用例が表示されます。フラグを推測するのではなく、これを参照してください。

主な落とし穴

1. pplx auth login は TTY 専用（非表示の対話型プロンプト）で、非対話型での使用は厳しく拒否されます。エージェントとして使用する場合は、代わりに PERPLEXITY_API_KEY 環境変数を設定してください。auth logout と auth login <key> は存在しません。
2. --stdout-preview は保存先ディレクトリを指定しないと何もしません。 結果を --output-dir DIR または $PPLX_OUTPUT_DIR で保存する場合に限り、長い文字列フィールドが切り詰められます（...<truncated> マーカー）。これだけを指定すると、出力は完全なサイズになります。また、ヒットごとに数 KB に及ぶことがあるため、デフォルトの検索でも数十 KB の結果が返る場合があります。
3. search web に追加した位置引数のクエリは、個別の検索ではなく、同じ検索の言い換えです（1 つの質問に対する再現率向上のため）。異なるトピックが N 個ある場合は、N 回呼び出してください。content snippets では、追加の位置引数は別の URL であり、言い換えではありません。
4. すべての失敗は、空の stdout と stderr 上の JSON エラーオブジェクト 1 つだけを伴って終了コード 1 を返します（{"error":{"code","message","command","hint"?}}）。失敗時は stdout ではなく stderr を解析してください。コードには AUTHENTICATION、UNKNOWN_ARGUMENT、ARGUMENT_ERROR、BAD_REQUEST が含まれます（これらに限りません。error.code に基づいて分岐してください）。
5. 日付フラグでは ISO 形式ではなく MM/DD/YYYY を使用します（例：--published-after-date 07/01/2026）。
6. --recency-filter と日付範囲指定を組み合わせないでください。 サーバーは --recency-filter と --published-after/before-date の組み合わせを BAD_REQUEST（「recency cannot be used together with published_after or published_before」）として拒否します。これはクライアント側では検出されず、無駄な往復が発生します。
7. content snippets の終了コード 0 は、すべての URL の処理が成功したことを意味しません。 URL ごとの失敗は、成功レスポンス内の results[i].error に含まれます。text を使用する前に、各結果でこれを確認してください。