web-search-with-perplexity

CLI wrapper for the Perplexity AI API. Three commands: search, ask, chat.

⚠️ #1 Agent Mistake — Global Flags Come BEFORE the Subcommand

# ✅ CORRECT
perplexity-cli --text ask "What is Rust?"
perplexity-cli --pretty search "AI news"
perplexity-cli --api-key sk-xxx ask "question"

# ❌ WRONG — typer silently ignores trailing global flags
perplexity-cli ask "What is Rust?" --text
perplexity-cli search "AI news" --pretty

--text, --pretty, and --api-key belong to the root command, not the subcommand. They must precede search, ask, or chat.

Commands at a Glance

Default is compact JSON — best for agents piping to jq.

Output Format Flags (global — must precede subcommand)

Quick Examples

# Search
perplexity-cli search "Python 3.13 features"
perplexity-cli --text search "best Python ORMs"

# Ask (non-streaming)
perplexity-cli ask "What is quantum computing?"
perplexity-cli --text ask "Latest Rust release" --recency month
perplexity-cli ask "Compare React vs Vue" --model sonar-pro

# Chat (streaming)
perplexity-cli --text chat "Explain monads"
perplexity-cli chat "AI news" --model sonar-pro 2>/dev/null  # final JSON only

# jq extraction
perplexity-cli ask "What is TLS?" | jq -r '.content'
perplexity-cli ask "Python packaging" | jq '.citations[]'

Research Methodology — Read Before Composing Queries

Many small queries beat one monolithic ask. A composite "compare A vs B vs C and tell me which" produces shallow surface-level output. Several focused queries — followed by reflection on the answers, then a new round of follow-ups — produce dramatically better synthesis.

Start broad, circle in. Hyper-specific opening questions anchor the model to your prompt's bias instead of the actual landscape. Open wide, see what comes back, then narrow to the real questions surfaced by Round 1.

Pattern: broad ask → reflect on answer → narrower asks on what surfaced → reflect → synthesis ask. Full templates and rules of thumb in patterns/SKILL.md.

Detailed References

Load these when you need full option tables, schemas, or patterns:

• Full command syntax + all flags → commands/SKILL.md
• JSON input/output schemas → schemas/SKILL.md
• Agent recipes + piping patterns → patterns/SKILL.md
• Model selection guide → models/SKILL.md

Setup — do it ONCE, then run bare commands

Preferred: a config file at ~/.config/perplexity-cli/perplexity-cli.json (honors $XDG_CONFIG_HOME). Put your keys and preferred defaults there, then just run perplexity-cli ask "..." — no env vars, no --api-key, no repeating --model/--recency on every call.

{
  "perplexity_api_key": "pplx-...",      // chmod 600 — this holds secrets
  "openrouter_api_key": "sk-or-v1-...",  // optional fallback
  "model": "sonar-pro",                   // default model for ask/chat
  "output": "json",                       // json | pretty | text
  "search_mode": "web",                   // optional defaults: search_mode, recency,
  "recency": "month",                     //   reasoning_effort, temperature
  "reasoning_effort": "high",
  "temperature": 0.2
}

All fields optional. Missing file = ignored. Unknown key / bad value = exit 4 (no silent ignore). If the file is group/world-readable the CLI prints a one-line chmod 600 warning. Only pass flags to override the config for a single call.

Env vars also work (and override the config file) if you prefer:

export PERPLEXITY_API_KEY="pplx-..."        # primary backend; or pass --api-key globally
export OPENROUTER_API_KEY="sk-or-v1-..."    # fallback backend (also works standalone)

Precedence (highest wins): CLI flag > env var > config file > built-in default.

Backend resolution:

--api-key only sets the Perplexity key. OpenRouter key is env-only.

Fallback caveats:

• search on the OpenRouter path emulates via perplexity/sonar-pro chat. Returns url + name (title), but snippet is always null — OpenRouter doesn't expose snippet text.
• chat streaming fallback only triggers before the first chunk emits. Mid-stream errors propagate (no restart, would duplicate stdout).
• JSON output schema unchanged regardless of backend.

Exit codes: 0 success · 2 auth/usage error · 3 rate limit · 4 validation · 5+ server error