Perplexity CLI (pplx): Agent Web Search Setup Guide

Coding agents increasingly need fresh web results and primary-source text. Browser automation and homegrown search wrappers often fail on DOM drift, inconsistent JSON shapes, and hard-to-reproduce setup.

📑Table of Contents

1. pplx vs browser automation
2. Install and authentication
3. Core commands: search web and content fetch
4. Wiring Claude Code and Cursor
5. Adoption checklist
6. FAQ
7. Summary: three steps today

What pplx provides

Perplexity CLI (pplx) is Perplexity’s official terminal client for the Search API. On success it prints one JSON object to stdout.

The two core commands share the same contract for humans and coding agents:

• pplx search web (ranked hits)
• pplx content fetch (cleaned page text plus metadata)

---

What this guide covers

This guide follows the official README and Agent Skill, plus same-week independent coverage, covering install, auth, filters, Claude Code wiring, and a go/no-go checklist.

---

pplx vs browser automation

Design focus

pplx is not a click-through browser. It is a JSON-first CLI over Perplexity’s Search API, designed so humans and coding agents share the same contract.

---

Feature comparison

Item	pplx (official CLI)	Browser agent / custom wrapper
Provider	Official GitHub perplexityai/perplexity-cli	Each tool or in-house code
Output	One JSON object on stdout (success)	HTML/DOM or ad-hoc JSON
Core commands	pplx search web / pplx content fetch	Clicks, scrapes, session scripts
Auth	PERPLEXITY_API_KEY (agents) or TTY auth login	Cookies/sessions are common
OS	macOS arm64; Linux x86_64 & arm64 (no native Windows)	Environment-specific
Agent wiring	Official Agent Skill + Claude Code plugin docs	Custom prompts / MCP
Updates	pplx update (checksum; no API key)	Manual follow-up

---

Sources

Source: perplexityai/perplexity-cli, pplx-cli Agent Skill (as of July 2026).

---

What search and fetch return

search web returns:

• hits (url, title, domain, snippet, …)
• total

content fetch returns cleaned text and metadata, including:

• error
• is_paywall

TechDaily (2026-07-25) independently summarized the same two agent-facing operations on the launch window, which corroborates availability beyond the origin GitHub repo.

---

When to prefer which

Use a browser agent when you must drive a logged-in UI.

Prefer pplx when you need:

• filterable hit lists
• cleaned text with an explicit paywall flag before you trust the body

---

Install and authentication

Supported OS

Official binaries cover three platforms only. Native Windows is out of scope; third-party guides mention WSL2, but that path is not on the official matrix.

Platform	Asset
macOS Apple Silicon	pplx-aarch64-apple-darwin.bin
Linux x86_64	pplx-x86_64-linux-gnu.bin
Linux arm64	pplx-aarch64-linux-gnu.bin

Source: perplexityai/perplexity-cli README (July 2026).

---

Install steps

One-liner install (SHA-256 verified, no sudo, default ~/.local/bin/pplx):

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

Source

Verification:

1. Put ~/.local/bin on PATH
2. Run pplx --version (calver-style string)

Manual install uses the platform binary plus SHA256SUMS. Override the install path with PPLX_INSTALL_PATH if needed.

---

Auth and updates

Auth rules:

1. Create a key at Perplexity API
2. For agents/CI: export PERPLEXITY_API_KEY=pplx-... (preferred)
3. Interactive only: pplx auth login (TTY required; piped input is rejected)
4. If both env and stored key exist, env wins
5. Missing credentials surface as AUTHENTICATION on real commands

Do not put auth login in agent or CI scripts. The official skill documents env-based auth for non-interactive runs.

Update and uninstall:

• Update: pplx update / pplx update --check (checksum verified; no API key; v0.2.2+)
• Uninstall: remove the binary, receipt, and credentials paths

---

Core commands: search web and content fetch

search web

pplx search web "Perplexity CLI pplx install"

---

Useful flags

• Count: -n 5 (default 10)
• Domains: --domains wikipedia.org,arxiv.org / --excluded-domains
• Relative window: --recency-filter week (hour/day/week/month/year)
• Date bounds: --published-after-date / --published-before-date (MM/DD/YYYY, not ISO)
• Country: --country (default US)
• Token control: --output-dir DIR --stdout-preview=200

---

Success, failure, and forbidden combinations

Success: exit 0 and one JSON object on stdout. Failure: exit 1, empty stdout, one JSON error on stderr (error.code). Extra positionals are reformulations of the same question, not separate topics—run another invocation for a new topic.

⚠️ Do not combine --recency-filter with published-after/before dates (server BAD_REQUEST). Also, --stdout-preview is a no-op without --output-dir or PPLX_OUTPUT_DIR.

---

content fetch

pplx content fetch https://example.com

Only http(s) URLs. Before trusting content, check:

• error
• is_paywall

The paywall flag is detection, not bypass.

Ops notes:

• Prefer save + preview with --html because raw_html can be large
• Use --no-cache for live fetches
• Set PPLX_OUTPUT_DIR and write CLAUDE.md rules so agents do not dump huge JSON into context

Search/Sonar usage is metered; whether Pro includes it is not fixed in the README—confirm in the dashboard and skip search when training data is enough.

---

Wiring Claude Code and Cursor

Skill and plugin

The README documents both a skill URL path and a Claude Code plugin path.

Skill prompt example from the README:

Read https://raw.githubusercontent.com/perplexityai/api-platform-developers/main/skills/pplx-cli/SKILL.md, install the skill, and use it for search.

Claude Code plugin:

1. /plugin marketplace add perplexityai/api-platform-developers
2. /plugin install perplexity-platform@api-platform-developers

---

Operational baseline

Operational baseline:

1. Inject PERPLEXITY_API_KEY from a secret store (never TTY login in agents)
2. Document when to search, -n caps, and output-dir + preview in CLAUDE.md
3. Keep project-level skills aligned with those rules
4. Compare with always-on MCP: call the CLI only when needed to control cost and context

---

CLI vs MCP

In the author’s setup, MCP was used heavily in the past, but CLI paths usually keep context smaller and are easier for agents to drive, so migrations lean toward CLI where a binary exists.

MCP remains useful when:

• no CLI is available
• the binary cannot be placed where the agent runs

Per-project CLAUDE.md and skill tuning remains essential so search timing and token caps stay consistent.

---

Related tooling

If the job is UI interaction rather than JSON retrieval, compare with browser tooling such as Claude Code Desktop’s in-app browser.

Adjacent agent CLI design references:

• ax for coding agents
• Claude Code harness overview
• Claude Code Setup plugin

---

Minimum path

Minimum path for readers:

1. Run install.sh and pplx --version
2. Set PERPLEXITY_API_KEY
3. Smoke-test pplx search web "test" -n 3 (try domains or recency once)
4. Run content fetch and inspect error / is_paywall
5. Install skill or plugin and write one CLAUDE.md paragraph of call rules

---

Adoption checklist

Adopt when

• Agents need machine-readable web hits and cleaned text
• You can run macOS arm64 or Linux binaries (or Linux via WSL)
• You accept a Perplexity API key and metered usage
• You want JSON stdout for jq / tool calls

---

Skip or replace when

• Windows-only with no WSL
• The goal is UI automation or login-wall bypass
• Offline-only or no external API policy
• An internal search API already owns contract and audit requirements

---

Ops checklist

• ✓ Confirmed supported OS
• ✓ Documented install.sh or manual SHA-256 path
• ✓ Stored PERPLEXITY_API_KEY for agents
• ✓ Banned auth login in CI
• ✓ Shared rule: never combine recency with date bounds
• ✓ Check error / is_paywall before trusting fetch
• ✓ Use --output-dir + preview to limit tokens
• ✓ Wrote CLAUDE.md call conditions
• ✓ Assigned monthly pplx update --check

---

FAQ

Q1. Does it run on Windows?

Official binaries are macOS arm64 and Linux only. Native Windows is unsupported. WSL2 appears in third-party guides, not the official matrix.

---

Q2. Can agents use pplx auth login?

No—TTY only. Use PERPLEXITY_API_KEY for agents/CI.

---

Q3. Does --stdout-preview alone shorten output?

No. It works only with --output-dir or PPLX_OUTPUT_DIR.

---

Q4. Can dates use ISO (YYYY-MM-DD)?

Official format is MM/DD/YYYY. Combining recency-filter with date bounds returns BAD_REQUEST.

---

Q5. Fastest Claude Code path?

marketplace add → plugin install, or have the agent read and install the skill URL. Pass the key via env.

---

Q6. Is usage included in Pro?

The CLI authenticates with an API key; Search/Sonar metering applies. Pro inclusion is not settled in the README—check the dashboard.

---

Summary: three steps today

pplx is a short, official path to give coding agents fresh web hits and primary text as JSON. It does not replace every browser workflow; its strength is a stable search/fetch contract.

Do this today:

1. Install and verify with pplx --version
2. Set PERPLEXITY_API_KEY and run pplx search web "test" -n 3
3. Attach the skill/plugin and write CLAUDE.md call rules

Keep five guardrails in the team runbook: OS limits, no TTY login for agents, no recency+date combo, fetch error/paywall checks, and metered cost. Next depth: secret management, domain allowlists, and monthly updates.

Related articles:

• 13580
• 13621
• 13623