Perplexity has released pplx, a command line client for its Search API that returns JSON results without a conversational interface. The tool is designed for both human operators and coding agents, stripping away model selection and synthesised answers to deliver only grounded search data and extracted text.
Two surfaces, one output contract
The application exposes two specific commands. pplx search web runs a live web search, while pplx content fetch pulls a URL and returns cleaned page text.
The official agent skill documentation defines success strictly as an exit code of 0 and exactly one JSON object on standard output. A search returns a structure containing hits, total, and saved_to. Any failure exits with code 1 and outputs an empty standard output stream.
One JSON error object goes to standard error instead, shaped as {"error":{"code","message","command","hint"?}}. Documented error codes include AUTHENTICATION, UNKNOWN_ARGUMENT, ARGUMENT_ERROR and BAD_REQUEST. The skill notes that this list is not exhaustive, so callers should branch on error.code.
Install path and platform support
Installation is a single shell command that pipes a script into sh:
curl -fsSL https://github.com/perplexityai/perplexity-cli/releases/latest/download/install.sh | shReading install.sh shows what it actually does. It downloads manifest.json from the latest release and extracts the tag and version. It then pins every remaining download to that tag, explicitly to avoid racing a concurrent publish.
It fetches SHA256SUMS and the platform binary, verifies the checksum, and installs to ~/.local/bin/pplx. No sudo is required. A receipt is written to ~/.config/pplx/pplx-receipt.json, but only after the installed binary runs successfully.
Platform coverage is limited to three targets: macOS on Apple Silicon, Linux x86_64 and Linux arm64. Anything else exits with an error. There is no Windows build and no Intel macOS build.
Context-window economics are a first-class design concern
The most agent-specific feature is token budgeting. --output-dir writes the full result set to a JSON file. --stdout-preview[=<CHARS>] truncates long string fields in stdout, adding ...<truncated> markers.
The skill is blunt about the trap: --stdout-preview is a no-op without a save directory. It truncates only when the result is also saved via --output-dir or $PPLX_OUTPUT_DIR. Used alone it returns full-size output, and hits can be multiple KB each.
Saved search results land at {dir}/web/{rand}.json and fetches at {dir}/fetch/{rand}.json. Files are written only after a successful request. PPLX_OUTPUT_DIR sets a workspace default so the flag need not be repeated.
For content fetch, the skill adds a correctness check rather than a cost one. Verify error and is_paywall in the output before trusting content. --html adds a raw_html field fetched live via crawler, and --no-cache forces a live fetch.
Key Takeaways
pplxis a single verified binary exposing two commands:pplx search webandpplx content fetch.- Success is exit 0 plus one JSON object on stdout; failures put one JSON error object on stderr.
pplx auth loginis TTY-only, so agents and CI must exportPERPLEXITY_API_KEY.--stdout-previewonly truncates when paired with--output-diror$PPLX_OUTPUT_DIR.- Search API billing is $5.00 per 1,000 requests, capped at 50 QPS on every usage tier.
Sources: perplexityai/perplexity-cli, pplx-cli SKILL.md, api-platform-developers, Perplexity API pricing, Rate limits and usage tiers, and Search API quickstart
Related articles
