mcpField
P
pplx-cli

pplx-cli

github.com/perplexityaiProductivity8364 installsUpdated 2w ago
Repository

About pplx-cli

pplx-cli is a skill for installing, authenticating, and using Perplexity’s `pplx` CLI. It helps agents and command-line users run web searches and retrieve query-relevant page snippets as JSON.

Key features

  1. 01Perplexity web search via CLI
  2. 02Retrieve page snippets from URLs
  3. 03Save full JSON results to files
  4. 04Configure search scope and token limits

Use cases

  1. 01Search the web for current technical information
  2. 02Extract relevant excerpts from selected pages

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/perplexityai/api-platform-developers --skill pplx-cli

After installing, type/pplx-cliin Claude Code to confirm it loaded.

Details

From the project README

pplx - Perplexity's web search and page-snippets CLI

What this skill does

Installs, authenticates, and drives Perplexity's public pplx CLI: pplx search web for live web search, pplx content snippets for query-relevant page excerpts. Output contract: success = exit 0 and exactly one JSON object on stdout; failures are pitfall 4.

Install

Skip if pplx --version already works (prints a calver like 2026.07.30.1785394496+1b7382b).

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

SHA-256-verified, no sudo, installs to ~/.local/bin/pplx (override: PPLX_INSTALL_PATH); ensure ~/.local/bin is on PATH. Platforms: macOS arm64, Linux x86_64, Linux arm64 - only. Update with pplx update (checksum-verified in-place replacement, no API key needed); pplx update --check only reports whether a newer release exists.

Auth

To auth run: pplx auth login if not authed already (interactive, needs a terminal; keys: https://www.perplexity.ai/account/api). In non-interactive sessions (agents, CI) export PERPLEXITY_API_KEY instead - auth login rejects piped input (pitfall 1).

The env var takes precedence over a key stored by interactive pplx auth login (<config>/perplexity/credentials.json; macOS ~/Library/Application Support, Linux $XDG_CONFIG_HOME or ~/.config). No configured key results in an AUTHENTICATION error on the first real command. Keys are redacted from all CLI output; the CLI talks to https://api.perplexity.ai.

Search

pplx search web "kubernetes pod OOMKilled causes"

Stdout: {hits: [{url, title, domain, snippet?, ...}], total, saved_to?}. To keep tokens down, save-and-preview - the extra positional here is a rewording of the same question (pitfall 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

That keeps stdout to a few KB, with saved_to (plus truncated when any field was actually cut) and the full JSON at out/web/{rand}.json (written only after a successful request) - read the file when the preview is not enough. Set PPLX_OUTPUT_DIR once to a workspace-appropriate path to give every command a default save dir instead of repeating --output-dir. More scoping flags (--domains, date bounds, --recency-filter, --country, token budgets): see pplx search web --help.

Snippets

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

1-50 http(s) URLs; here the extra positionals are ADDITIONAL PAGES to excerpt, not query rephrasings (the opposite of search web, pitfall 3). Stdout: {results: [{url, text?, tokens_count?, error?}], saved_to?} - one result per URL. Check error on every result before trusting text - exit 0 means the request succeeded, not that every URL did (pitfall 7); a failed URL has error set and no text. Elided regions inside text are marked with …. Token budgets: --max-tokens = total across all snippets, 1-16384, default 4096; --max-tokens-per-page = per page, 1-4096, must be <= --max-tokens, default min(1024, max_tokens). Saved file: {dir}/snippets/{rand}.json. The query is positional-only: -q/--query and --no-cache are UNKNOWN_ARGUMENT parse errors here. Binaries v0.2.2 and older fail with an unknown-command error on content snippets - run pplx update first. content fetch is removed; use content snippets.

When unsure

Every subcommand's --help prints full flag docs plus Input shape, Stdout shape, Saved file schema, and examples - consult it instead of guessing flags.

Top pitfalls

  1. pplx auth login is TTY-only (hidden interactive prompt) and hard-rejects non-interactive use - as an agent, set the PERPLEXITY_API_KEY env var instead. auth logout and auth login <key> do not exist.
  2. --stdout-preview is a no-op without a save dir. It truncates long string fields (...<truncated> markers) only when the result is also saved via --output-dir DIR or $PPLX_OUTPUT_DIR; alone, you get full-size output - and hits can be multi-KB each, so a default search can return tens of KB.
  3. Extra positional queries on search web are reformulations of the SAME search (recall boosters for one question), not separate searches. N distinct topics = N invocations. On content snippets extra positionals are more URLs, never rephrasings.
  4. Every failure exits 1 with empty stdout and exactly one JSON error object on stderr ({"error":{"code","message","command","hint"?}}) - parse stderr, not stdout, on failure. Codes include AUTHENTICATION, UNKNOWN_ARGUMENT, ARGUMENT_ERROR, BAD_REQUEST (not exhaustive; branch on error.code).
  5. Date flags use MM/DD/YYYY, not ISO dates (e.g. --published-after-date 07/01/2026).
  6. Don't combine --recency-filter with date bounds. The server rejects --recency-filter + --published-after/before-date as BAD_REQUEST ("recency cannot be used together with published_after or published_before") - a wasted round trip, not caught client-side.
  7. Exit 0 from content snippets does not mean every URL succeeded. Per-URL failures ride a successful response as results[i].error; check it on each result before using text.

Comments

Markdown supported