Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ Each skill is a self-contained directory with a SKILL.md plus supporting referen
| Skill | What it does | When to use |
|---|---|---|
| migrate-sonar-to-agent-api | Migrates a codebase from Perplexity's Sonar API (chat completions) to the Agent API: endpoints, request params, model slugs, response parsing, streaming, citations | Migrating off Sonar or chat completions, replacing deprecated sonar-pro / sonar-reasoning models, or fixing 400 unknown-field errors and missing citations after a migration attempt |
| pplx-cli | Installs and uses Perplexity's public `pplx` CLI: SHA-verified install, API-key auth, `search web`, `content snippets`, JSON output handling | Needing live web search results or query-relevant excerpts from specific URLs from the terminal, or installing and authenticating the pplx command |
| pplx-cli | Installs and uses Perplexity's public `pplx` CLI: SHA-verified install, API-key auth, `search web`, `content snippets`, unauthenticated `changelog`, JSON output handling | Needing live web search results, page excerpts, or recent Perplexity API changes from the terminal, or installing and authenticating the pplx command |
| pplx-search-sdk | Installs and uses Perplexity's public Python Search SDK (`pplx-srch-sdk`, import `pplx_srch_sdk`): API-key auth, `search.web`, `web_many` fan-out, `content.snippets`, typed errors, async client | Needing live web search or query-relevant page excerpts from Python code - scripts, notebooks, research pipelines - rather than from the terminal |

## Triggers

When migrating code from Perplexity's Sonar API (chat completions) to the Agent API, or debugging 400 unknown-field errors / missing citations after such a migration, use the $migrate-sonar-to-agent-api skill.
When you need live web search results or query-relevant excerpts from specific URLs from the terminal, or need to install the Perplexity `pplx` CLI, use the $pplx-cli skill.
When you need live web search results, query-relevant page excerpts, or recent Perplexity API changes from the terminal, or need to install the Perplexity `pplx` CLI, use the $pplx-cli skill.
When you need live web search or query-relevant page excerpts from Python code, or need to install Perplexity's `pplx-srch-sdk` / `pplx_srch_sdk` Python SDK, use the $pplx-search-sdk skill.

## Repo layout
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Read https://raw.githubusercontent.com/perplexityai/api-platform-developers/main
| Skill | Invoke | What it does |
|---|---|---|
| migrate-sonar-to-agent-api | `/perplexity-platform:migrate-sonar-to-agent-api [path]` (Claude Code) or `$migrate-sonar-to-agent-api` (Codex) | Migrates a codebase from Sonar chat completions to the Agent API |
| pplx-cli | `/perplexity-platform:pplx-cli [query or URL]` (Claude Code) or `$pplx-cli` (Codex) | Installs and uses the `pplx` CLI for live web search and query-relevant page snippets |
| pplx-cli | `/perplexity-platform:pplx-cli [query, URL, or API changelog question]` (Claude Code) or `$pplx-cli` (Codex) | Installs and uses the `pplx` CLI for live web search, query-relevant page snippets, and the public API changelog |
| pplx-search-sdk | `/perplexity-platform:pplx-search-sdk [query or URLs]` (Claude Code) or `$pplx-search-sdk` (Codex) | Installs and uses the `pplx-srch-sdk` Python SDK for live web search, concurrent query fan-out, and query-relevant page snippets |

Skills also auto-trigger on matching context (for example, "help me migrate from Sonar") once installed.
Expand Down
40 changes: 31 additions & 9 deletions skills/pplx-cli/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
---
name: pplx-cli
description: "Install and use Perplexity's pplx CLI for live web search and query-relevant page snippets from the terminal. Use to search the web, look up current information or news, get query-relevant excerpts from specific URLs, or install and authenticate the pplx command."
when_to_use: "Any request like: search the web for X, find the latest news about X, look up current events, use Perplexity to search, search with pplx, install the pplx CLI, set up the Perplexity CLI, get query-relevant excerpts from specific URLs, what do these pages say about X, restrict a web search to certain domains or dates."
argument-hint: "[search query or URL]"
description: "Install and use Perplexity's pplx CLI for live web search, query-relevant page snippets, and the API changelog. Use to search the web, get excerpts from URLs, check Perplexity API changes and deprecations before recommending an integration, or install and authenticate pplx."
when_to_use: "Any request like: search the web for X, find the latest news about X, look up current events, use Perplexity to search, search with pplx, install the pplx CLI, set up the Perplexity CLI, get query-relevant excerpts from specific URLs, what do these pages say about X, restrict a web search to certain domains or dates, what changed in the Perplexity API, check recent API deprecations or model updates."
argument-hint: "[search query, URL, or API changelog question]"
---

# pplx - Perplexity's web search and page-snippets CLI
# pplx - Perplexity's web search, page-snippets, and API changelog 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.
Installs and drives Perplexity's public `pplx` CLI: `pplx search web` for live web search, `pplx content snippets` for query-relevant page excerpts, and `pplx changelog` for public API updates without authentication.
Output contract: success = exit 0 and exactly one JSON object on stdout; failures are pitfall 4.

## Install
Expand All @@ -26,12 +26,34 @@ Update with `pplx update` (checksum-verified in-place replacement, no API key ne

## Auth

Only search and snippets need an API key. For API updates, go directly to [API changelog](#api-changelog).

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`.
No configured key results in an `AUTHENTICATION` error on search or snippets.
Keys are redacted from all CLI output; search and snippets use `https://api.perplexity.ai`.

## API changelog

When asked what changed in the Perplexity API, or when recent capabilities, model updates, or deprecations affect an integration recommendation, read the changelog before giving guidance:

```sh
pplx changelog
pplx changelog --limit 20
```

The command reads the public docs RSS feed at `https://docs.perplexity.ai/docs/resources/changelog/rss.xml` without credentials. It works before `pplx auth login`; do not request an API key for it.

If `pplx changelog --help` reports an unknown command, run `pplx update`. If it is still unavailable, read `https://docs.perplexity.ai/docs/resources/changelog` directly.

- Stdout: `{entries: [{headline, tags, url, date, content}]}`. `tags` is an array of strings; the other entry fields are strings.
- Default: up to five entries. `--limit` accepts integers from 1 through 20 and returns only as many entries as the feed contains.
- Preserve feed order, which follows the changelog page. `date` is the feed-reported date normalized to RFC 3339, not necessarily the original publication date.
- `content` is HTML. A leading bold headline is lifted into `headline`; when absent, the feed title is used and the body stays intact.
- Summarize relevant entries and cite their `url` values. For older history, follow the full changelog page; the feed is a limited window, so an absent entry does not establish that a feature is unavailable.
- On failure, use the stderr error contract below: `CHANGELOG_FETCH_FAILED` means check connectivity and retry; `FEED_PARSE_FAILED` means update the CLI or consult the changelog page. An out-of-range `--limit` returns `VALUE_VALIDATION`. Report a failed read as unavailable evidence, not as "no updates."

## Search

Expand All @@ -48,7 +70,7 @@ pplx search web "kubernetes pod OOMKilled causes" "why does k8s keep killing my
```

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`.
Set `PPLX_OUTPUT_DIR` once to a workspace-appropriate path to give search and snippets 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
Expand All @@ -69,7 +91,7 @@ Binaries v0.2.2 and older fail with an unknown-command error on `content snippet

## 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.
Consult each subcommand's `--help` instead of guessing flags. Search and snippets also document input, stdout, saved-file shapes, and examples there. Changelog output is already JSON; it has no `--json` or `--output-dir` flag.

## Top pitfalls

Expand Down