Perplexity CLI

The pplx CLI returns structured JSON from the Perplexity Search API, making it useful for shell pipelines, interactive terminal work, and coding agents that need current web results or query-relevant page snippets.

Install

Open the agent in your project and send it this:

text

Read https://github.com/perplexityai/api-platform-developers/blob/main/skills/pplx-cli/SKILL.md and install this skill, then use it to search the web from my terminal.

Without an agent, run the installer yourself:

Bash

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

Authenticate

Every command needs a Perplexity API key. Choose one authentication method:

Bash

export PERPLEXITY_API_KEY="your_api_key_here"

Bash

pplx auth login

Search the web

Bash

pplx search web "what is a bloom filter" -n 2

Response

JSON

{
  "total": 2,
  "hits": [
    {
      "url": "https://en.wikipedia.org/wiki/Bloom_filter",
      "title": "Bloom filter",
      "domain": "en.wikipedia.org",
      "snippet": "In computing, a **Bloom filter** is a space-efficient probabilistic data structure, conceived by Burton Howard ...",
      "summary": "In computing, a **Bloom filter** is a space-efficient probabilistic data structure, conceived by Burton Howard ...",
      "date": "2004-04-17",
      "last_updated": "2026-07-08",
      "trust": {
        "level": 2,
        "name": "trusted",
        "description": "is trusted for community-edited general knowledge and reference articles across education, science, history, and many non-controversial topics worldwide."
      }
    },
    {
      "url": "https://systemdesign.one/bloom-filters-explained/",
      "title": "Bloom Filters Explained - System Design",
      "domain": "systemdesign.one",
      "snippet": "## What is a bloom filter?\nA Bloom filter is a space-efficient probabilistic data structure that is used to te ...",
      "summary": "## What is a bloom filter?\nA Bloom filter is a space-efficient probabilistic data structure that is used to te ...",
      "date": "2023-03-06",
      "last_updated": "2026-07-13",
      "trust": {
        "level": 1,
        "name": "credible",
        "description": "is credible for personally authored software system design case studies and interview preparation content without formal institutional peer review."
      }
    }
  ]
}

Filter results

These flags scope a search. They are the Search API filters, so their behavior and limits are identical — see domain filter and date and time filters for the details.

Bash

pplx search web "AI inference hardware" \
  --domains arxiv.org,nvidia.com \
  --published-after-date 07/01/2026 \
  -n 5

Flag	Format	Description	Example
`--domains`	Comma-separated hostnames	Return results only from these domains	`--domains arxiv.org,nvidia.com`
`--excluded-domains`	Comma-separated hostnames	Drop results from these domains	`--excluded-domains reddit.com,quora.com`
`--published-after-date`	`MM/DD/YYYY`	Published on or after this date	`--published-after-date 07/01/2026`
`--published-before-date`	`MM/DD/YYYY`	Published on or before this date	`--published-before-date 07/31/2026`
`--updated-after-date`	`MM/DD/YYYY`	Last modified on or after this date	`--updated-after-date 07/01/2026`
`--updated-before-date`	`MM/DD/YYYY`	Last modified on or before this date	`--updated-before-date 07/31/2026`
`--recency-filter`	`hour`, `day`, `week`, `month`, `year`	Relative window instead of explicit dates	`--recency-filter week`
`--country`	ISO 3166-1 alpha-2 code	Region the search runs for, `US` by default	`--country DE`

Ask the same question several ways

Extra positional queries are rephrasings of one question, not separate searches. The CLI still returns a single ranked result set, but wording the question more than one way surfaces pages that only match the phrasing you did not think of first:

Bash

pplx search web \
  "kubernetes pod OOMKilled causes" \
  "why does k8s keep killing my pod with OOMKilled"

Save full results

Save the complete result while keeping stdout small:

Bash

pplx search web "kubernetes pod OOMKilled causes" \
  --output-dir out \
  --stdout-preview=200

The full response is written under out/web/, and stdout includes its path in saved_to. --stdout-preview only truncates stdout when you also set --output-dir or PPLX_OUTPUT_DIR. Cut strings end in ...<truncated> and the response gains a top-level "truncated": true.

Search errors

A search either succeeds or fails outright: on failure nothing reaches stdout and the JSON error object goes to stderr. The search-specific code is BAD_REQUEST, which the service returns when the filters contradict each other, as with --recency-filter alongside a publication-date bound. Everything else you can hit here is a common error.

Generate query-relevant snippets

Extract the passages of a page that are relevant to a query, instead of retrieving the whole page:

Bash

pplx content snippets "how does a bloom filter decide set membership" \
  https://en.wikipedia.org/wiki/Bloom_filter

Response

JSON

{
  "results": [
    {
      "url": "https://en.wikipedia.org/wiki/Bloom_filter",
      "text": "In computing, a **Bloom filter** is a space-efficient probabilistic data structure, conceived by Burton Howard Bloom in 1970, that is used to test whether an element is a member of a set. False positive matches are possible, but false negatives are not ...",
      "tokens_count": 1047
    }
  ]
}

text keeps only the query-relevant passages of the page; elided regions in between are marked with the … character.

Cover several pages in one call

Extra positional URLs are additional pages, not rephrasings: unlike pplx search web, where extra positional arguments reword one question, each URL here is snipped independently against the same query. One call takes up to 50 URLs:

Bash

pplx content snippets "bloom filter false positive rate" \
  https://en.wikipedia.org/wiki/Bloom_filter \
  https://systemdesign.one/bloom-filters-explained/ \
  --max-tokens-per-page 256

Response

JSON

{
  "results": [
    {
      "url": "https://en.wikipedia.org/wiki/Bloom_filter",
      "text": "More generally, fewer than 10 bits per element are required for a 1% false positive probability, independent of the size or number of elements in the set.\n\n…\n\nIf all are 1, then either the element is in the set, *or* the bits have by chance been set to 1 during the insertion of other elements, resulting in a false positive. ...",
      "tokens_count": 261
    },
    {
      "url": "https://systemdesign.one/bloom-filters-explained/",
      "text": "### Bloom filter false positive\n\nIn Figure 5, the bloom filter is queried to check the membership of item *green*, which is not a member of the bloom filter. ...",
      "tokens_count": 262
    }
  ]
}

Budget the tokens

Two flags cap how much text comes back.

Flag	Range	Default	Description
`--max-tokens`	`1`–`16384`	`4096`	Maximum total tokens across all snippets
`--max-tokens-per-page`	`1`–`4096`	`min(1024, max_tokens)`	Maximum tokens for any single page's snippet; must not exceed `--max-tokens`

Budgets are approximate: a snippet can run a few tokens over its cap, as the tokens_count values above show.

Snippet errors

pplx content snippets reports failure per URL, not per command. A page that cannot be snipped does not fail the run: the command still exits 0, and that URL's result carries an error message with no text.

Bash

pplx content snippets "example domain reserved documentation" \
  https://www.iana.org/help/example-domains \
  https://www.example.com/nonexistent/

Response

JSON

{
  "results": [
    {
      "url": "https://www.iana.org/help/example-domains",
      "text": "1. Instructions and Guides\n\n# Example Domains\n\nAs described in RFC 2606 and RFC 6761, a number of domains such as example.com and example.org are maintained for documentation purposes. ...",
      "tokens_count": 152
    },
    {
      "url": "https://www.example.com/nonexistent/",
      "error": "no snippet could be generated under the requested token budget"
    }
  ]
}

Check every result for error before trusting its text, because a successful invocation does not mean every page produced a snippet.

Keep large responses out of stdout

Snippets across many URLs still add up. --output-dir writes the full response under <dir>/snippets/, and --stdout-preview truncates the long strings on stdout:

Bash

pplx content snippets "how does a bloom filter decide set membership" \
  https://en.wikipedia.org/wiki/Bloom_filter \
  --output-dir out \
  --stdout-preview=200

Response

JSON

{
  "results": [
    {
      "url": "https://en.wikipedia.org/wiki/Bloom_filter",
      "text": "In computing, a **Bloom filter** is a space-efficient probabilistic data structure, conceived by Burton Howard Bloom in 1970, that is used to test whether an element is a member of a set. False positi...<truncated>",
      "tokens_count": 1047
    }
  ],
  "saved_to": "out/snippets/c6989ad7.json",
  "truncated": true
}

Stdout carries the saved path in saved_to plus "truncated": true, so the terminal stays readable while the complete text sits on disk.

Handle errors

These are the failures common to every pplx command. A failed command writes one JSON error object to stderr:

JSON

{
  "error": {
    "code": "AUTHENTICATION",
    "message": "...",
    "command": "search.web",
    "hint": "Set the PERPLEXITY_API_KEY environment variable"
  }
}

Branch on error.code.

Error codes

Code	Raised when
`AUTHENTICATION`	No key is configured, or the key is invalid
`FORBIDDEN`	The key does not have access to what you requested
`RATE_LIMIT`	You are over your rate limit
`BAD_REQUEST`	The service rejected the request, for example `--recency-filter` combined with a date bound
`VALIDATION`	The service rejected a field value
`NOT_FOUND`	The requested resource does not exist
`TIMEOUT`	The request took too long
`CONNECT`	The CLI could not reach the API
`INTERNAL_SERVER`	The service failed
`UNKNOWN_ARGUMENT`	The flag does not exist on this command
`INVALID_VALUE`, `VALUE_VALIDATION`	A flag value is malformed or out of range
`MISSING_REQUIRED_ARGUMENT`, `MISSING_QUERY`	A required argument or the query is missing
`ARGUMENT_ERROR`	Any other argument-parsing failure

Run pplx <command> --help before assuming that a flag exists; CLI output is already JSON, so no --json flag is needed.

Next steps

See the perplexity-cli repository for release notes, manual installation, and uninstall instructions.

Search documentation

Getting Started

Router API

Agent API

Embeddings API

Perplexity SDK

Admin & Management

Resources

Perplexity CLI

Install

Authenticate

Search the web

Filter results

Ask the same question several ways

Save full results

Search errors

Generate query-relevant snippets

Cover several pages in one call

Budget the tokens

Snippet errors

Keep large responses out of stdout

Handle errors

Next steps

Getting Started

Router API

Agent API

Embeddings API

Perplexity SDK

Admin & Management

Resources