Perplexity CLI

Query Perplexity.ai from your terminal. Get answers with source citations, structured JSON output, real-time streaming, file attachments, and thread export -- all from a single command.

Try it now

No install required. Run directly with uvx:

uvx pxcli query "What happened in AI this week?"

That's it. You get an answer with source references, directly in your terminal.

Install

For regular use, install the package so pxcli is always available:

uv pip install pxcli

Both pxcli and perplexity-cli work as command names after installation.

Install from source

git clone https://github.com/jamiemills/perplexity-cli.git
cd perplexity-cli
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest  # verify setup

Quick start

1. Ask a question (no setup needed)

pxcli query "What is machine learning?"

2. Authenticate for full features (one-time, optional)

pxcli auth login

This connects to Chrome, waits for you to sign in to Perplexity.ai, and saves your session token encrypted locally. See Authentication setup for the full walkthrough.

3. Use everything

pxcli query --attach report.pdf "Summarise this document"
pxcli query --model claude46sonnet "Explain Docker"
pxcli query --json "What is Python?" | jq -r '.result.answer'
pxcli threads export

Shell shortcuts

Add these to your ~/.zshrc (or ~/.bashrc) for quick access:

# Quick question (rich terminal output, no citation markers)
px() { uvx pxcli query --strip-references --format rich "$*"; }

# Get just the commands to run (plain text)
pxc() { uvx pxcli query --strip-references --format plain "$*. Just give me the commands to run on a Mac. Put them on a single line"; }

# JSON answer only
pxj() { uvx pxcli query --json "$*" | jq -r '.result.answer'; }

Then:

px "what is the latest version of Python?"
pxc "how can I find what remote branches exist for this repo"
pxj "what is the capital of France?"

Querying

Basic usage

# Rich terminal output (default when interactive)
pxcli query "What is machine learning?"

# Stream the response as it arrives
pxcli query --stream "What is machine learning?"

# Remove citation markers [1], [2] and the references section
pxcli query --strip-references "What is machine learning?"

# Read query from stdin
echo "What is Python?" | pxcli query -

# Set a timeout (seconds)
pxcli query --timeout 120 "Complex research question"

Output formats

The default is rich when stdout is a terminal, or plain when piped.

# Plain text (good for scripts, piping, saving to .txt)
pxcli query --format plain "What is Python?"

# GitHub-flavoured Markdown
pxcli query --format markdown "Explain Docker" > docker.md

# Structured JSON envelope (see JSON output section below)
pxcli query --json "What is Python?"

File attachments

Attach files to provide context for your query. Requires authentication.

# Single file
pxcli query --attach README.md "What is this project?"

# Multiple files (comma-separated)
pxcli query --attach config.json,data.txt "Analyse these files"

# Repeated flag
pxcli query -a file1.txt -a file2.txt "Compare these files"

# Entire directory (recursive)
pxcli query --attach ./docs "Summarise all documentation"

Model selection

Choose a specific model for your query:

pxcli query --model gpt54 "What is Python?"
pxcli query -m claude46sonnet "Explain Docker"

# List available models for your subscription tier
pxcli models list
pxcli models list --json | jq '.result.models[].model_id'

Combining flags

All flags compose freely:

pxcli query -f plain -S "What is 2+2?"
pxcli query --stream --strip-references "Explain Kubernetes"
pxcli query --format markdown -S "How does DNS work?" > dns.md
pxcli query --json --timeout 60 "Complex analysis question"
pxcli query --json --stream "What is Python?"

Query options reference

Option	Short	Description
`--format`	`-f`	`plain`, `markdown`, `rich` (default), `json`
`--json`		Structured JSON envelope output
`--stream` / `--no-stream`	`-s`	Stream response incrementally
`--strip-references`	`-S`	Remove citation markers and references section
`--attach`	`-a`	Attach file(s) or directory
`--model`	`-m`	Model identifier (see `pxcli models list`)
`--timeout`	`-t`	Request timeout in seconds (default: 60)
`--schema`		Embed JSON Schema in envelope (with `--json`)
`--request-param`		Inject extra key=value into API request (experimental)

JSON output

Every command that accepts --json produces a structured envelope on stdout. This makes pxcli straightforward to integrate into scripts, pipelines, and agent workflows.

Success envelope

{
  "ok": true,
  "command": "pxcli query",
  "result": {
    "answer": "Python is a high-level programming language...",
    "references": [
      {
        "index": 1,
        "title": "Python.org",
        "url": "https://www.python.org",
        "snippet": "Python is a programming language..."
      }
    ]
  },
  "meta": {
    "duration_ms": 1423,
    "version": "0.7.1",
    "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "truncated": false
  },
  "next_actions": [
    {
      "command": "pxcli query",
      "description": "Ask a follow-up question"
    }
  ]
}

Error envelope

When ok is false, the envelope contains error details and a suggested fix:

{
  "ok": false,
  "command": "pxcli query",
  "error": {
    "code": "authentication_required",
    "message": "File attachments require authentication.",
    "input": {}
  },
  "fix": "Run `pxcli auth login` to authenticate.",
  "next_actions": [
    { "command": "pxcli auth login", "description": "Authenticate with Perplexity.ai" }
  ]
}

Error codes: authentication_required, permission_denied, rate_limited, network_error, timeout, upstream_schema_error, configuration_error, attachment_error, validation_error, not_found, internal_error.

Result shapes by command

Command	`.result` fields
`query`	`{answer, references}`
`auth login`	`{token_path, cookies_stored}`
`auth logout`	`{credentials_existed}`
`auth status`	`{authenticated, token_path, token_age_days, cookies_stored, verified}`
`config set`	`{key, value}`
`config show`	`{config_path, save_cookies, debug_mode, env_overrides}`
`style set`	`{style}`
`style show`	`{style}`
`style clear`	`{had_style}`
`threads export`	`{threads, total, output_path, date_range}`
`models list`	`{models}`
`doctor security`	`{storage_backend, token_path, token_permissions, cache_path, cache_permissions, cookies_enabled}`
`skill show`	`{content}`

Working with jq

# Extract the answer text (use -r so newlines render properly)
pxcli query --json "What is Python?" | jq -r '.result.answer'

# Get reference URLs
pxcli query --json "What is Python?" | jq -r '.result.references[].url'

# Count references
pxcli query --json "What is Python?" | jq '.result.references | length'

# Get timing metadata
pxcli query --json "What is Python?" | jq '.meta.duration_ms'

# Check success
pxcli query --json "What is Python?" | jq '.ok'

# Get suggested next actions
pxcli query --json "What is Python?" | jq -r '.next_actions[].command'

NDJSON streaming

Use --json --stream together for structured streaming. Each line is a valid JSON object:

pxcli query --json --stream "What is Python?"

{"type": "start", "command": "pxcli query --json --stream", "ts": "2025-05-09T10:00:00+00:00"}
{"type": "chunk", "text": "Python is a", "ts": "2025-05-09T10:00:01+00:00"}
{"type": "chunk", "text": " high-level programming language...", "ts": "2025-05-09T10:00:02+00:00"}
{"type": "result", "ok": true, "command": "...", "result": {...}, "meta": {...}, "next_actions": [...], "ts": "2025-05-09T10:00:03+00:00"}

Event types: start (first line), chunk (incremental content), result (final line with full envelope).

Without --json, --stream produces raw text as it arrives.

JSON Schema

Retrieve the full Pydantic-generated schema for all envelope types:

pxcli schema                                    # full schema
pxcli schema | jq '.success_envelope'           # success envelope only
pxcli schema | jq '.commands'                   # per-command result definitions
pxcli schema | jq '.commands["query"]'          # query result schema

Or embed the schema inline with any --json response:

pxcli query --json --schema "What is Python?"   # adds $schema key to envelope

Scripting examples

Shell:

# Capture answer in a variable
ANSWER=$(pxcli query --format plain "What is 2+2?")
echo "The answer is: $ANSWER"

# Error handling with exit codes
pxcli query --json "Your question"
rc=$?
case $rc in
  0) echo "Success" ;;
  4) echo "Auth needed -- run: pxcli auth login" ;;
  6) echo "Transient error -- retrying..." && sleep 2 && pxcli query --json "Your question" ;;
  *) echo "Failed with exit code $rc" ;;
esac

# Check .ok before processing JSON
response=$(pxcli query --json "Your question")
if echo "$response" | jq -e '.ok' > /dev/null 2>&1; then
  echo "$response" | jq -r '.result.answer'
else
  echo "$response" | jq -r '.error.message' >&2
  echo "$response" | jq -r '.fix' >&2
fi

Python:

import json
import subprocess
import sys

result = subprocess.run(
    ["pxcli", "query", "--json", "What is Python?"],
    capture_output=True, text=True,
)

if result.returncode != 0:
    print(f"pxcli exited with code {result.returncode}", file=sys.stderr)
    sys.exit(result.returncode)

envelope = json.loads(result.stdout)

if not envelope["ok"]:
    print(f"Error: {envelope['error']['message']}", file=sys.stderr)
    print(f"Fix: {envelope['fix']}", file=sys.stderr)
    sys.exit(1)

print(envelope["result"]["answer"])
for ref in envelope["result"]["references"]:
    print(f"  [{ref['index']}] {ref['title']}: {ref['url']}")

Python (NDJSON streaming):

import json
import subprocess

proc = subprocess.Popen(
    ["pxcli", "query", "--json", "--stream", "What is Python?"],
    stdout=subprocess.PIPE, text=True,
)

for line in proc.stdout:
    event = json.loads(line)
    if event["type"] == "chunk":
        print(event["text"], end="", flush=True)
    elif event["type"] == "result":
        refs = event["result"]["references"]
        print(f"\n\n{len(refs)} references found.")

proc.wait()

Authentication setup

Authentication is optional for basic queries but required for file attachments (--attach), thread export, and model listing.

Step 1: Install Chrome for Testing

Download a dedicated Chrome instance (keeps testing separate from your main browser):

npx @puppeteer/browsers install chrome@stable

Step 2: Create a shell alias

Add to your ~/.zshrc or ~/.bashrc:

alias chromefortesting='open ~/.local/bin/chrome/mac_arm-*/chrome-mac-arm64/Google\ Chrome\ for\ Testing.app --args "--remote-debugging-port=9222" "about:blank"'

Adjust the path for your platform. The mac_arm-* pattern matches the version directory.

Step 3: Authenticate

# Terminal 1: Start Chrome with debugging enabled
chromefortesting

# Terminal 2: Run authentication
pxcli auth login

The process connects to Chrome, navigates to Perplexity.ai, waits for you to sign in, extracts your session token, and saves it encrypted to ~/.config/perplexity-cli/token.json.

Once complete, you do not need to authenticate again unless the token expires or you run pxcli auth logout.

Custom port

If port 9222 is in use, start Chrome with a different port and match it:

pxcli auth login --port 9223

Auth status

pxcli auth status                # local check
pxcli auth status --verify       # live API verification
pxcli auth status --json         # JSON envelope output

Logout

pxcli auth logout

What requires authentication?

Feature	Auth required?
`query` (basic)	No
`query --attach` (file attachments)	Yes
`models list`	Yes
`threads export`	Yes
`auth status`	No (reports unauthenticated state)
`style set/show/clear`	No (local only)
`config set/show`	No (local only)
`doctor security`	No (local only)
`schema`	No
`completion`	No
`skill show`	No

Response styles

Set a persistent style prompt that is appended to every query. This controls the tone and format of responses without repeating instructions.

# Set a style
pxcli style set "be brief and concise"

# View the current style
pxcli style show

# Clear the style
pxcli style clear

The style is stored in ~/.config/perplexity-cli/style.json and persists across sessions. All three commands accept --json for structured output.

Thread export

Export your Perplexity conversation history to CSV. Requires authentication.

# Export all threads
pxcli threads export

# Filter by date range
pxcli threads export --from-date 2025-01-01
pxcli threads export --from-date 2025-01-01 --to-date 2025-12-31

# Custom output file
pxcli threads export --output my-threads.csv

# Bypass local cache
pxcli threads export --force-refresh

# Clear cache before export
pxcli threads export --clear-cache

# JSON envelope output
pxcli threads export --json
pxcli threads export --json | jq '.result.threads[] | .title'

CSV format

title,created_at,url
"How does quantum computing work?",2025-05-08T14:30:00+00:00,https://www.perplexity.ai/search/...
"Best Python testing frameworks",2025-05-07T09:15:00+00:00,https://www.perplexity.ai/search/...

Fields: title, created_at (ISO 8601 with timezone), url.

Caching

Thread exports are cached locally in encrypted form at ~/.config/perplexity-cli/threads-cache.json. The cache is updated incrementally on each export. Use --force-refresh to bypass the cache or --clear-cache to delete it.

Thread export options

Option	Short	Description
`--from-date`		Start date filter, inclusive (YYYY-MM-DD)
`--to-date`		End date filter, inclusive (YYYY-MM-DD)
`--output`	`-o`	Output CSV path (default: `threads-TIMESTAMP.csv`)
`--force-refresh`		Bypass local cache
`--clear-cache`		Delete cache before export
`--json`		JSON envelope output instead of CSV
`--schema`		Embed JSON Schema in envelope (with `--json`)

Configuration

Feature toggles

Configuration is stored in ~/.config/perplexity-cli/config.json:

{
  "version": 1,
  "features": {
    "save_cookies": false,
    "debug_mode": false
  }
}

# View current configuration
pxcli config show

# Enable cookie storage (saves Cloudflare cookies alongside JWT token)
pxcli config set save_cookies true

# Enable persistent debug logging
pxcli config set debug_mode true

# Disable
pxcli config set save_cookies false
pxcli config set debug_mode false

After changing save_cookies, re-authenticate for the change to take effect:

pxcli config set save_cookies true
pxcli auth login

URL configuration

API endpoints are configured in ~/.config/perplexity-cli/urls.json (created automatically on first run):

{
  "perplexity": {
    "base_url": "https://www.perplexity.ai",
    "query_endpoint": "https://www.perplexity.ai/rest/sse/perplexity_ask",
    "thread_list_endpoint": "https://www.perplexity.ai/rest/thread/list_ask_threads",
    "upload_url_endpoint": "https://www.perplexity.ai/rest/uploads/batch_create_upload_urls",
    "s3_bucket_url": "https://ppl-ai-file-upload.s3.amazonaws.com/"
  },
  "rate_limiting": {
    "enabled": true,
    "requests_per_period": 20,
    "period_seconds": 60
  }
}

All endpoint fields are full URLs. If Perplexity changes an endpoint, update the relevant field without modifying any code.

Rate limiting

Rate limiting applies to thread export requests. Adjust in urls.json:

{
  "rate_limiting": {
    "enabled": true,
    "requests_per_period": 10,
    "period_seconds": 60
  }
}

Set "enabled": false to disable (not recommended).

Environment variables

Environment variables override configuration file settings. Precedence: CLI flags > environment variables > config file > defaults.

Variable	Description
`PERPLEXITY_BASE_URL`	API base URL
`PERPLEXITY_QUERY_ENDPOINT`	Query endpoint path
`PERPLEXITY_CONFIG_DIR`	Override config directory location
`PERPLEXITY_SAVE_COOKIES`	`true` / `false` -- override cookie storage
`PERPLEXITY_DEBUG_MODE`	`true` / `false` -- override debug mode
`PERPLEXITY_RATE_LIMITING_ENABLED`	`true` / `false`
`PERPLEXITY_RATE_LIMITING_RPS`	Requests per period (integer)
`PERPLEXITY_RATE_LIMITING_PERIOD`	Period in seconds (integer)
`XDG_CONFIG_HOME`	XDG base directory for config (default: `~/.config`)
`NO_COLOR`	Disable coloured output (any value)
`PXCLI_SESSION_LOG`	Set to `true` to enable NDJSON session logging

Shell completion

Generate tab-completion scripts for commands, subcommands, and options:

# Bash -- add to ~/.bashrc
eval "$(pxcli completion bash)"

# Zsh -- add to ~/.zshrc
eval "$(pxcli completion zsh)"

# Fish
pxcli completion fish | source

Diagnostics

Security report

pxcli doctor security
pxcli doctor security --json

Reports storage backend, token file path and permissions, cache file path and permissions, and whether cookie storage is enabled. Useful for verifying that credentials are stored with appropriate restrictions (e.g. 0600).

Live token verification

pxcli auth status --verify

Performs a live API check to confirm the stored token is valid, beyond simply checking local file state.

Logging

pxcli --verbose query "question"     # INFO level logging to stderr
pxcli --debug query "question"       # DEBUG level logging (HTTP details, timing)
pxcli --log-file /tmp/debug.log query "question"   # Log to file

Debug mode can also be enabled persistently:

pxcli config set debug_mode true

Agent integration

pxcli includes a built-in skill definition for AI agents and LLM-based toolchains:

pxcli skill show          # display the skill definition
pxcli skill show --json   # JSON envelope with skill content

The skill describes how agents can use pxcli as a web search and research tool, including JSON parsing patterns, NDJSON streaming integration, error handling, and workflow examples. The next_actions array in every JSON envelope suggests follow-up commands that agents can chain automatically.

Global options

These options apply to all commands:

Option	Short	Description
`--version`		Show version and exit
`--verbose`	`-v`	INFO level logging
`--debug`	`-d`	DEBUG level logging (overrides `--verbose`)
`--log-file PATH`		Log file path (default: `~/.config/perplexity-cli/perplexity-cli.log`)
`--quiet`	`-q`	Suppress non-essential output
`--no-color`		Disable coloured output

Command reference

Command tree

pxcli
|-- query QUERY [OPTIONS]          Submit a query
|-- schema                         Output JSON schema for envelopes
|-- auth
|   |-- login [--port PORT]        Authenticate via Chrome DevTools
|   |-- logout                     Remove stored credentials
|   +-- status [--verify]          Check authentication state
|-- config
|   |-- set KEY VALUE              Set a configuration option
|   +-- show                       Display current configuration
|-- models
|   +-- list                       List available models
|-- style
|   |-- set STYLE                  Set a persistent style prompt
|   |-- show                       View current style
|   +-- clear                      Remove style
|-- threads
|   +-- export [OPTIONS]           Export thread library to CSV
|-- skill
|   +-- show                       Display agent skill definition
|-- doctor
|   +-- security                   Report credential storage state
+-- completion
    |-- bash                       Generate Bash completion script
    |-- zsh                        Generate Zsh completion script
    +-- fish                       Generate Fish completion script

All subcommands under auth, config, models, style, threads, skill, doctor, and completion accept --json and --schema for structured output (where applicable).

Exit codes

Code	Meaning
`0`	Success
`1`	General failure
`2`	Usage error (bad arguments, missing input)
`3`	Not found
`4`	Authentication required
`5`	Conflict
`6`	Transient error (timeout, rate limit -- retry may help)
`7`	Validation error
`130`	Interrupted (Ctrl+C)

For scripting, prefer checking the exit code first. In --json mode, both success and error responses are valid JSON envelopes on stdout -- check the .ok field.

Security

Tokens encrypted at rest using Fernet symmetric encryption
Key derived via PBKDF2-HMAC with 100,000 iterations from the system hostname and OS user
File permissions restricted to owner only (0600)
Token validity checked on each request, with age warnings after 30 days
No credentials written to logs
Cookie storage is opt-in and uses the same encrypted file

This is machine-bound obfuscation rather than OS keychain-backed secret storage. It prevents casual copying between machines but does not protect against other local processes that can already read the token file. If cookie storage is enabled, browser cookies are stored alongside the token and should be treated as sensitive session material.

Token storage locations

Platform	Path
Linux / macOS	`~/.config/perplexity-cli/token.json`
Windows	`%APPDATA%\perplexity-cli\token.json`

Troubleshooting

Problem	Solution
"Not authenticated"	Run `pxcli auth login`
"Failed to decrypt token"	Token was encrypted on a different machine or user. Run `pxcli auth login` to re-authenticate.
Chrome connection fails	Ensure Chrome is running with `--remote-debugging-port=9222` and the port matches.
Token file has insecure permissions	Delete the file and re-authenticate: `rm ~/.config/perplexity-cli/token.json && pxcli auth login`

Prerequisites

Python 3.12 or later
Google Chrome (for initial authentication only)

Development

Setup

git clone https://github.com/jamiemills/perplexity-cli.git
cd perplexity-cli
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
uv run lefthook install

Testing

uv run pytest                   # safe default test suite (1369 tests)
uv run pytest -m security       # security tests only
uv run pytest -m fuzz           # fuzz tests (17 atheris harnesses)

Makefile

The Makefile is the single source of truth for all lint, test, and build commands. Both CI (GitHub Actions) and local git hooks (lefthook) delegate to it.

make ci                         # run the full CI pipeline locally
make lint                       # ruff + bandit + vulture + semgrep
make test                       # pytest with coverage
make build                      # build wheel and sdist

Releasing

Use the release target to bump the version, run CI, commit, tag, and push:

make release V=0.8.0

This runs uv lock, the full CI pipeline, commits the version bump, creates a v0.8.0 tag, and pushes both to origin. The publish-to-pypi workflow then publishes to PyPI via OIDC trusted publishing.

The detailed release workflow is documented in .claude/PUBLISHING.md.

Compatibility

Supported Python versions: 3.12+. CI tests against 3.12.

Project governance

Contributing guide: CONTRIBUTING.md
Security policy: SECURITY.md
Licence: LICENSE
Changelog: GitHub Releases

Licence

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 197 Commits
.github		.github
.home/.config/perplexity-cli		.home/.config/perplexity-cli
.opencode/plugins		.opencode/plugins
.sonar		.sonar
scripts		scripts
src/perplexity_cli		src/perplexity_cli
tests		tests
.gitignore		.gitignore
.safety-project.ini		.safety-project.ini
.semgrep.yml		.semgrep.yml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
lefthook.yml		lefthook.yml
opencode.json		opencode.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock
vulture_whitelist.py		vulture_whitelist.py

Folders and files

Latest commit

History

Repository files navigation

Perplexity CLI

Try it now

Install

Quick start

1. Ask a question (no setup needed)

2. Authenticate for full features (one-time, optional)

3. Use everything

Shell shortcuts

Querying

Basic usage

Output formats

File attachments

Model selection

Combining flags

Query options reference

JSON output

Success envelope

Error envelope

Result shapes by command

Working with jq

NDJSON streaming

JSON Schema

Scripting examples

Authentication setup

Step 1: Install Chrome for Testing

Step 2: Create a shell alias

Step 3: Authenticate

Custom port

Auth status

Logout

What requires authentication?

Response styles

Thread export

CSV format

Caching

Thread export options

Configuration

Feature toggles

URL configuration

Rate limiting

Environment variables

Shell completion

Diagnostics

Security report

Live token verification

Logging

Agent integration

Global options

Command reference

Command tree

Exit codes

Security

Token storage locations

Troubleshooting

Prerequisites

Development

Setup

Testing

Makefile

Releasing

Compatibility

Project governance

Licence

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Uh oh!

Contributors

Uh oh!

Languages