pplx

Modern CLI for the Perplexity AI API. Search, query, reason, and research from your terminal.

Install

Requires Node.js 20+

From npm

npm install -g @pruddiman/pplx

From source

git clone https://github.com/PatrickRuddiman/pplx.git
cd pplx
npm install
npm run install:global

This builds the project and installs pplx as a global command. To uninstall:

npm run uninstall:global

Development (symlink)

For active development, use npm link so changes are reflected immediately after rebuild:

npm install
npm run link          # builds and symlinks pplx globally
npm run dev           # watch mode - rebuilds on file changes

To remove the symlink:

npm run unlink

Run without installing

npx @pruddiman/pplx "What is quantum computing?"

Setup

Get an API key from perplexity.ai/account/api, then:

pplx config set-key YOUR_API_KEY

Or set the environment variable:

export PERPLEXITY_API_KEY=your-key-here

Usage

Quick Query (Default)

pplx "What is the capital of France?"

No subcommand needed - just pass your question directly.

Query with Options

# Use a specific model
pplx query "Explain quantum computing" --model sonar-pro

# Disable streaming (wait for full response)
pplx query "Write a haiku" --no-stream

# Save response to file
pplx query "Summarize recent AI news" --output summary.txt

# Academic search mode
pplx query "CRISPR gene therapy trials" --search-mode academic

# Filter by recency
pplx query "Latest TypeScript features" --recency week

# Restrict to specific domains
pplx query "React best practices" --domain reactjs.org --domain github.com

# Show related follow-up questions
pplx query "Climate change effects" --related

# Use reasoning model with high effort
pplx query "Analyze trade-offs of microservices" --model sonar-reasoning-pro --reasoning high

# Raw output for piping
pplx query "List 10 programming languages" --raw | head -5

Search

Get search results with sources:

pplx search "renewable energy trends 2026"
pplx search "machine learning papers" --mode academic
pplx search "SEC filings Tesla" --mode sec
pplx search "news today" --recency day --json

Deep Research

Run expert-level research (async, may take minutes):

# Start research and wait for results
pplx research start "Comprehensive analysis of mRNA vaccine technology"

# Start research without waiting
pplx research start "Topic" --no-wait

# Check status
pplx research status <request-id>

# Get completed results
pplx research get <request-id> --output report.txt

# Shorthand
pplx research "Topic"

Conversation Threads

Continue previous conversations:

pplx query "What is Rust?"
pplx query "How does its borrow checker work?" --continue
pplx query "Compare it to C++" --thread <thread-id>

Other Commands

# List available models
pplx models

# View query history
pplx history
pplx history --limit 50
pplx history --threads
pplx history --clear

# Configuration
pplx config set-key <key>
pplx config view-key
pplx config clear-key
pplx config set model sonar-pro      # Change default model
pplx config set contextSize high     # Change default search depth
pplx config list
pplx config path

Models

| Model | Type | Best For | |-------|------|----------| | sonar | Search | Quick queries, summaries, current events | | sonar-pro | Search | Complex queries, follow-ups, 2x citations | | sonar-reasoning-pro | Reasoning | Step-by-step analysis, logical problem-solving | | sonar-deep-research | Research | Comprehensive reports, multi-source synthesis |

Query Options

| Flag | Description | |------|-------------| | -m, --model <model> | Model to use (default: sonar) | | -s, --stream | Stream response in real-time (default) | | --no-stream | Wait for complete response | | -o, --output <file> | Save response to file | | --search-mode <mode> | web, academic, or sec | | --recency <period> | hour, day, week, month, year | | --after <date> | Results after date (YYYY-MM-DD) | | --before <date> | Results before date (YYYY-MM-DD) | | --domain <domains...> | Include only these domains | | --exclude-domain <domains...> | Exclude these domains | | --images | Include images (sonar-pro only) | | --related | Show related questions | | --reasoning <effort> | minimal, low, medium, high | | --context-size <size> | Search depth: low, medium, high | | --language <code> | Response language | | --system <prompt> | Custom system prompt | | --json | JSON output format | | --no-citations | Hide citation sources | | --no-search | Disable web search | | --safe-search | Enable safe search | | --raw | Raw text output (no formatting) | | -c, --continue | Continue last conversation | | -t, --thread <id> | Continue a specific thread |

Global Options

| Flag | Description | |------|-------------| | --api-key <key> | Override stored API key | | --verbose | Show debug output | | --no-color | Disable colors |

Environment Variables

| Variable | Description | |----------|-------------| | PERPLEXITY_API_KEY | API key (overrides stored config) | | PERPLEXITY_MODEL | Default model | | PERPLEXITY_CONFIG_DIR | Custom config directory | | NO_COLOR | Disable colors |

License

MIT