A fast, single-binary CLI for the Perplexity API, built in Rust.
Query the web from your terminal with real-time streaming, markdown rendering, citations, cost tracking, and full access to every Perplexity API parameter.
# Homebrew (macOS/Linux)
brew install osodevops/tap/pplx
# Pre-built binaries — download from GitHub Releases
# https://github.com/osodevops/perplexity-cli/releases
# From source
cargo install --git https://github.com/osodevops/perplexity-cliRun the one-time setup to store your Perplexity API key:
pplx config init
# Enter your Perplexity API key: pplx-...
# Config created at: ~/.config/pplx/config.toml
# You're ready to go! Try: pplx "What is Rust?"This creates ~/.config/pplx/config.toml with your key. You only need to do this once.
Alternatively, set the key as an environment variable:
export PERPLEXITY_API_KEY="pplx-..."# Ask anything (ask is the default subcommand)
pplx "What causes aurora borealis?"
# Pick a model
pplx ask -m sonar "Quick: capital of France?"
pplx ask -m sonar-reasoning-pro "Prove that sqrt(2) is irrational"
# Set a persona with a system prompt
pplx ask -s "You are a senior Rust developer" "Review this error handling pattern"
# Pipe content as context
cat error.log | pplx ask "What's causing this error?"
# JSON output for scripting
pplx ask --no-stream -o json "Top 5 Rust web frameworks" | jq '.citations'
# Search filters
pplx ask --domain arxiv.org --recency month "transformer architecture improvements"
pplx ask --search-mode academic "CRISPR clinical trials 2025"
pplx ask --after 01/01/2025 --context-size high "EU AI Act enforcement updates"
# Show citations, usage stats, and cost
pplx ask --citations --usage --cost "Latest developments in fusion energy"
# Reasoning models — show chain-of-thought
pplx ask -m sonar-reasoning-pro --reasoning "Is P = NP?"
# Save output to file
pplx ask --save report.md "Summarize recent AI breakthroughs"
# Shell completions
pplx completions zsh > ~/.zsh/completions/_pplx# Raw web search (returns URLs, titles, snippets)
pplx search "Rust async runtime benchmarks"
# Multi-query search
pplx search "Rust tokio" "Rust async-std"
# With filters
pplx search --domain docs.rs --max-results 5 "serde derive"# Submit and wait for results
pplx research "Comprehensive analysis of WebAssembly adoption in 2025"
# Submit async and check later
pplx research --async "Long research topic"
pplx research status <job-id>
pplx research get <job-id>
# List all research jobs
pplx research list# Use third-party models through Perplexity
pplx agent -m openai/gpt-4o "Explain monads"
# Enable tools
pplx agent --tool web_search --tool fetch_url "Latest Rust release notes"# Start a session
pplx interactive
# In the REPL:
# /model sonar-pro — switch model
# /clear — reset conversation
# /cost — show session costs
# /help — list commands
# /quit — exit# Set defaults
pplx config set model sonar-pro
pplx config set output plain
pplx config set temperature 0.7
# View current config
pplx config show- Real-time streaming — responses stream token-by-token with a search spinner
- Markdown rendering — built-in terminal rendering with syntax highlighting
- Multiple output formats —
md(default),plain,json,raw - All API parameters exposed — model, temperature, top-p, search mode, domain filters, recency, date ranges, context size, reasoning effort
- Citations — numbered source URLs below responses
- Cost tracking — per-request cost breakdown (input/output/request/citation/reasoning/search)
- Token usage — prompt, completion, and total token counts
- Pipe-friendly — reads from stdin, disables colours when piped, works with
jq - Layered config — CLI flags > environment variables > TOML config file > defaults
- Shell completions — bash, zsh, fish, PowerShell
- Retry with backoff — automatic retry on 429/5xx with exponential backoff
- Cross-platform — macOS (Apple Silicon + Intel), Linux, Windows
- Zero runtime dependencies — single statically-linked binary
| Model | Best For |
|---|---|
sonar |
Quick factual lookups (~1200 tok/s) |
sonar-pro |
Complex queries, multi-step search (200K context) |
sonar-reasoning-pro |
Chain-of-thought reasoning, math, analysis |
sonar-deep-research |
Comprehensive autonomous research reports |
pplx config init creates ~/.config/pplx/config.toml. Edit it to set defaults:
[auth]
api_key = "pplx-..."
[defaults]
model = "sonar-pro"
output = "md"
temperature = 0.7
show_citations = true
show_cost = false
[defaults.search]
mode = "web"
recency = "month"
exclude_domains = ["pinterest.com", "quora.com"]Check your current effective config:
pplx config showPrecedence: CLI flags > environment variables > config file > built-in defaults
| Variable | Description |
|---|---|
PERPLEXITY_API_KEY |
API key (required) |
PPLX_MODEL |
Default model |
PPLX_OUTPUT |
Default output format |
PPLX_CONTEXT_SIZE |
Default search context size |
# Rendered markdown (default) — colours, bold, code highlighting
pplx "Explain async/await in Rust"
# Plain text — no formatting, clean for piping
pplx ask -o plain "summarize this" < article.txt
# JSON — full API response for programmatic use
pplx ask -o json "top databases 2025" | jq '.citations[]'
# Raw — response content only, no metadata
RESULT=$(pplx ask -o raw "current BTC price")pplx [OPTIONS] [QUERY]... [COMMAND]
Commands:
ask Send a query (default if no subcommand given)
search Raw web search via Search API
research Deep research with async support
agent Agent API with third-party models
interactive Start interactive REPL session
config Manage configuration (init, show, set)
completions Generate shell completions
Global Options:
-m, --model <MODEL> Model to use [default: sonar-pro]
-o, --output <FORMAT> Output format: md, plain, json, raw
-s, --system <PROMPT> System prompt
-c, --citations Show citations
-u, --usage Show token usage
--cost Show cost breakdown
--no-stream Disable streaming
--no-color Disable colour output
--verbose Enable debug logging
--config <PATH> Config file path override
Search Filters:
--search-mode <MODE> web, academic, sec
--domain <DOMAIN> Include domain (repeatable)
--exclude-domain <DOMAIN> Exclude domain (repeatable)
--recency <PERIOD> hour, day, week, month, year
--after <DATE> Results after date (MM/DD/YYYY)
--before <DATE> Results before date (MM/DD/YYYY)
--context-size <SIZE> minimal, low, medium, high
Model Parameters:
--max-tokens <N> Maximum response tokens
-t, --temperature <FLOAT> Temperature (0.0-2.0)
--top-p <FLOAT> Nucleus sampling (0.0-1.0)
--reasoning-effort <LVL> minimal, low, medium, high
Response Enrichment:
--images Return image URLs
--related Return related questions
--search-results Show full search result metadata
--no-search Disable web search
--smart-search Enable search classifier
--reasoning Show reasoning/thinking blocks
--json-schema <SCHEMA> JSON schema for structured output
--save <PATH> Save response to file
git clone https://github.com/osodevops/perplexity-cli
cd perplexity-cli
cargo build --release
# Binary at target/release/pplxRequirements: Rust 1.75+
# Run tests
cargo test
# Lint
cargo clippy --all-targets -- -D warnings- Phase 1: Core MVP —
askcommand, streaming, output formats, config, citations, cost, retry, completions - Phase 2: Search & Filters —
searchcommand (Search API),--json-schema,--save, image/related rendering - Phase 3: Advanced —
interactiveREPL,research(async deep research),agent(third-party models),<think>block rendering - Phase 4: Polish — man pages, input validation,
config set, expanded test suite,--versionwith git hash, AUR/Nix packaging