pplx-cli

A cookie-authenticated CLI for Perplexity AI. Built for headless and agentic usage — no browser required at runtime, no API key, no per-call billing beyond your existing Perplexity Pro subscription.

npm install -g pplx-npx-search
pplx auth --browser auto
pplx auth --test
pplx search "what shipped in Claude 4.7 this week" --json --raw

That's the whole loop. Cookies live at ~/.config/pplx/cookies.json, never paste them by hand.

Why this exists

Perplexity has no public consumer-tier API. Power users who already pay for Pro want shell and agent access without paying again per-call for the API. pplx-cli reads the cookies from your already-signed-in browser and uses them headlessly, so:

• No API key. Cookies come from your real session.
• No re-billing. Calls count against your existing Pro quota.
• Agent-friendly. --json and --raw flags are designed for piping into LLMs, agents, and scripts.
• TLS fingerprinting fallback. When Cloudflare gets aggressive, the CLI auto-falls back to Playwright or curl-impersonate.

This is a ground-up Node.js reimplementation inspired by the reverse-engineering work in helallao/perplexity-ai — see Acknowledgements.

Prerequisites

• Node.js 20 or newer
• A logged-in session in Chrome, Chrome Beta, Comet, or Dia (macOS) or Google Chrome (Linux)
• Optional: Playwright Chromium (npx playwright install chromium) for the --playwright transport

Quick Start

1. Log into Perplexity in your browser

Before anything else, open one of the supported browsers (Chrome, Chrome Beta, Comet, or Dia) and make sure you are signed into perplexity.ai. The CLI extracts cookies from your real session; if you are not logged in, there is nothing to extract.

2. Install the CLI

npm install -g pplx-npx-search

# or run once without installing
npx pplx-npx-search search "what is quantum computing"

If you would rather build from source:

git clone https://github.com/thatsrajan/pplx-cli.git
cd pplx-cli
npm install
npm link

3. Extract cookies once

pplx auth --browser auto

--browser auto tries every supported browser in turn and uses the first one that yields a valid signed-in session. Force a specific browser if you have multiple installed:

pplx auth --browser chrome
pplx auth --browser chrome-beta
pplx auth --browser comet
pplx auth --browser dia

If the browser stores are locked down (corporate machine, weird Keychain ACL, etc.) you can fall back to Playwright:

pplx auth --playwright

Cookies are written to ~/.config/pplx/cookies.json.

Security: never commit cookies.json to a repo or paste its contents into a chat. The file is a complete session credential. The CLI never asks you to type cookies by hand and never logs them to stdout.

4. Verify

pplx auth --test

This must report ✓ Cookies are valid before agents start calling the CLI. If it fails, repeat step 1 (you may be signed out) then step 3.

5. Use it

pplx search "what is quantum computing"
pplx reason "explain the Riemann hypothesis"
pplx research "compare React vs Vue in 2026"
pplx labs "hello world"          # free, no auth needed
pplx computer new "compare dinner options nearby"
pplx council new "critique the competitive threat from Acme in enterprise search"
pplx models                       # list available models

Agent Usage

pplx-cli is designed to be the Perplexity transport for AI agents, CI jobs, and headless scripts.

# Plain text output, no colors, no spinner
pplx search "query" --raw

# Single JSON object: { answer, sources, query, mode, model }
pplx search "query" --json

# Read query from stdin
echo "what is 2+2" | pplx search -

# Pipe-friendly: auto-detects non-TTY
pplx search "query" | head -1

# Non-zero exit when no answer is returned
pplx search "query" --json || echo "failed"

Deep Research is slower than normal search. pplx research defaults to a 10-minute stream timeout; override it per run with --timeout-ms 600000, --timeout-ms 120s, or --timeout-ms 10m.

Recommended agent invocation:

pplx search "research this topic" --json --raw --mode pro

--json --raw gives a clean, deterministic envelope with no chrome around it:

{
  "answer": "...",
  "sources": [
    {"title": "...", "url": "..."}
  ],
  "query": "...",
  "mode": "pro",
  "model": "...",
  "artifactDir": "/Users/you/.config/pplx/artifacts/...",
  "artifactId": "..."
}

MCP Server

pplx-mcp exposes the same Perplexity workflow through a local stdio MCP server for Claude Desktop, Claude Code, Codex, and other MCP clients.

pplx-mcp

Typical global client registrations:

claude mcp add --scope user pplx -- /path/to/node /path/to/pplx-mcp
codex mcp add pplx -- /path/to/node /path/to/pplx-mcp

For Claude Desktop, add the server under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pplx": {
      "command": "/path/to/node",
      "args": ["/path/to/pplx-mcp"]
    }
  }
}

The MCP server exposes:

• pplx_search: authenticated search, reasoning, and deep-research queries with sources and artifacts.
• pplx_labs: Labs model queries that do not require cookie auth.
• pplx_auth_status: validates the stored Perplexity browser cookies.
• pplx_models: lists known model aliases.
• pplx_computer_create, pplx_computer_status, pplx_computer_read_task, and pplx_computer_import: Perplexity Computer artifact handoff tools.
• pplx_council_create, pplx_council_status, pplx_council_read_task, and pplx_council_import: Perplexity Model Council artifact handoff tools.

Artifacts

Query-producing commands save artifacts by default:

• pplx search
• pplx reason
• pplx research
• pplx labs
• bare pplx "query"
• pplx computer new
• pplx council new

Each run gets a folder containing meta.json, query.txt, answer.md, result.json, and sources.json. Use --out <dir> to choose the destination for one run, or set "artifactDir" in ~/.config/pplx/config.json to make it persistent. Use --artifact-id <id> when an agent needs a deterministic run folder, and --no-artifact to disable saving for one search-style run.

pplx search "compare laptops under $1500" --out ~/Dropbox/pplx-runs
pplx research "best places to stay in Kyoto" --artifact-id kyoto-research
pplx search "what is 2+2" --no-artifact --json --raw

pplx computer is an artifact handoff for Perplexity Computer. It creates a task prompt and a result contract without calling private Computer APIs:

pplx computer new "compare dinner options nearby" --out ~/Dropbox/pplx-runs
pplx computer open <run-id> --copy
pplx computer status <run-id> --out ~/Dropbox/pplx-runs
pplx computer import <run-id> --out ~/Dropbox/pplx-runs --json

Computer runs include task.md, result.schema.json, and computer-result.json. Paste task.md into Perplexity Computer; when the task is done, place the structured result in computer-result.json so local agents can read it.

pplx council is an artifact handoff for Perplexity Model Council. It requires Model Council access in the Perplexity web UI and creates a task prompt plus result contract without claiming a private Council API:

pplx council new "critique the competitive threat from Acme in enterprise search" --out ~/Dropbox/pplx-runs
pplx council new "review this evidence" --evidence ~/Dropbox/pplx-runs/acme/computer-result.json
pplx council open <run-id> --copy
pplx council status <run-id> --out ~/Dropbox/pplx-runs
pplx council import <run-id> --out ~/Dropbox/pplx-runs --json

Council runs include task.md, result.schema.json, and council-result.json. Paste task.md into Perplexity Model Council; when the review is done, place the structured result in council-result.json so local agents can read it.

Options

| Flag | Description | |---|---| | --mode auto\|pro\|reasoning\|deep-research | Search mode | | --model claude-3.5-sonnet | Pin a specific model | | --json | Single JSON object output | | --raw | Plain text, no colors, no spinner | | --chrome | Use Chrome CDP bridge instead of HTTP | | --playwright | Use Playwright headless Chromium | | --no-playwright | Force HTTP transport even if config enables Playwright | | --timeout-ms 120000\|120s\|10m | Overall stream timeout | | --out <dir> | Directory for saved artifacts | | --artifact-id <id> | Deterministic artifact id for this run | | --no-artifact | Disable artifact saving for one search-style run | | --curl | Force curl-impersonate (auto-downloads if missing) | | --allow-anonymous | Allow anonymous Perplexity responses when cookies are expired | | --incognito | Do not save the query to Perplexity history | | --citations-full | Show full source metadata in the rendered answer |

Architecture

| Layer | Detail | |---|---| | Default transport | Headless HTTP with stored cookies. No browser launched at runtime. | | Optional transports | --chrome Chrome CDP bridge, --playwright Playwright headless Chromium, --curl curl-impersonate for TLS fingerprinting. | | Auto fallback | HTTP → Playwright → curl-impersonate when TLS is blocked. | | Streaming | Real-time answer streaming via Server-Sent Events. | | Auth | One-time cookie extraction from Chrome / Chrome Beta / Comet / Dia (macOS Keychain) or ~/.config/google-chrome (Linux). After that, fully headless. | | Session validation | pplx auth --test and pplx auth --browser auto both verify that the extracted cookies resolve to an authenticated session (not just "I extracted some bytes"). |

Configuration

Optional config file at ~/.config/pplx/config.json:

{
  "mode": "pro",
  "model": "claude-3.5-sonnet",
  "lang": "en-US",
  "playwright": true,
  "playwrightHeadless": false,
  "artifactDir": "/Users/you/Dropbox/pplx-runs"
}

Set "playwright": true to make Playwright the default transport.

Environment overrides:

PPLX_CURL_IMPERSONATE=/path/to/curl-impersonate-chrome

Troubleshooting

| Symptom | Fix | |---|---| | Cookies are invalid or expired | Open Perplexity in your browser, confirm you are signed in, then re-run pplx auth --browser auto. | | Keychain access denied for "Chrome Safe Storage" | macOS Keychain is prompting for permission. Run the exact security find-generic-password command the error suggests and click "Always Allow". | | Chrome cookie DB not found at ... | The selected browser is not installed at the default location, or the profile name is wrong. Pass --browser <name> or --profile <name>. | | Search hangs or times out | TLS fingerprinting may be in play. Try pplx search "..." --playwright or --curl. | | npm install -g succeeds but pplx not found | Your global npm bin directory is not on PATH. Find it with npm bin -g and add it. |

Acknowledgements

This project was inspired by and built upon the reverse-engineering work in helallao/perplexity-ai — a Python library for the Perplexity AI API. The authentication flow, SSE protocol handling, and API structure were all derived from studying that project. Big thanks to @helallao for figuring out the hard parts.

pplx-cli is a ground-up Node.js reimplementation for CLI and agentic use cases, but it would not exist without that foundational work.

License

MIT