Perplexity AI Search

Overview

This skill provides access to the Perplexity API for web-grounded AI search and research. It combines the power of large language models with real-time web search, providing accurate, up-to-date answers with source citations.

When to Use Perplexity vs. Built-in Search

Use Perplexity when:

You need current information (news, prices, events, recent developments)
The user asks for source citations or references
Complex multi-step reasoning is required
The user specifically mentions Perplexity or wants research-style answers
You need exhaustive analysis across multiple sources

Use built-in web search when:

Simple factual queries
Quick information lookup
The user doesn't need AI-generated synthesis
Basic URL or content retrieval is sufficient

Model Selection Guide

Choose the right model based on task complexity:

🔍 Search Models (Quick Facts)

Use for simple, factual queries where speed matters.

sonar - Default search model with web access. Best for most queries.
sonar-pro - Advanced search with deeper understanding.

🧠 Reasoning Models (Complex Analysis)

Use for complex, multi-step tasks requiring logical thinking.

sonar-reasoning - Complex reasoning with web search.
sonar-reasoning-pro - Advanced reasoning with deeper content understanding.

📚 Research Models (Exhaustive Analysis)

Use for comprehensive, in-depth research across multiple sources.

sonar-research - Comprehensive research with in-depth analysis.
sonar-research-pro - Advanced research with exhaustive analysis and detailed reports.

Quick Start

Basic Search

# Simple query (uses sonar by default)
scripts/perplexity_search.sh "What is the capital of Germany?"

# With custom model
scripts/perplexity_search.sh "Latest AI developments" -m sonar-pro

# Markdown format with citations
scripts/perplexity_search.sh "Tesla stock analysis" -f markdown

Advanced Research

# Deep research with comprehensive analysis
scripts/perplexity_search.sh "Market analysis for electric vehicles in 2025" \
  -m sonar-research-pro -c high -f markdown

# Pro search mode (multi-step reasoning)
scripts/perplexity_search.sh "Compare AI models performance benchmarks" \
  -m sonar-reasoning-pro -p pro -f markdown

# With custom system prompt
scripts/perplexity_search.sh "Analyze tech trends" \
  -s "You are a technology analyst. Focus on business implications and market trends."

Search Context Size

Control how much web information is retrieved:

low - Faster, fewer sources. Good for simple queries.
medium (default) - Balanced. Good for most use cases.
high - Most comprehensive. Best for research and detailed analysis.

Pro Search Mode

Available for sonar-pro and reasoning models. Controls multi-step tool usage:

fast (default) - Standard single-step search.
pro - Automated multi-step reasoning with multiple web searches.
auto - Automatic classification based on query complexity.

Setup Requirements

API Key Configuration

The skill automatically looks for the Perplexity API key in this order:

Environment Variable PERPLEXITY_API_KEY (recommended)
Clawdbot Config ~/.clawdbot/clawdbot.json under auth.profiles.perplexity:default.apiKey

To set the environment variable (temporary, per session):

export PERPLEXITY_API_KEY="your-key-here"

To set it permanently:

# Add to ~/.bashrc or ~/.zshrc
echo 'export PERPLEXITY_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

Or add to Clawdbot config:

{
  "auth": {
    "profiles": {
      "perplexity:default": {
        "provider": "perplexity",
        "mode": "api_key",
        "apiKey": "your-key-here"
      }
    }
  }
}

Dependencies

The script uses bash and curl. Both are typically pre-installed on Linux systems.

Usage Patterns

News and Current Events

scripts/perplexity_search.sh "Latest news about AI regulation in Europe" -m sonar

Competitive Analysis

scripts/perplexity_search.sh "Compare iPhone 15 vs Samsung Galaxy S24 features" \
  -m sonar-reasoning-pro -c high -f markdown

Market Research

scripts/perplexity_search.sh "Electric vehicle market forecast 2025-2030" \
  -m sonar-research-pro -c high -p pro -f markdown

Technical Questions with Current Data

scripts/perplexity_search.sh "Latest Python frameworks for web development 2025" \
  -m sonar-reasoning -c medium

Output Formats

text (default) - Plain text with citation references [1], [2], etc.
markdown - Markdown formatted response with source links
json - Raw API response in JSON format

Cost Awareness

Perplexity API is not free. Be mindful of usage costs:

Simple queries: ~$0.005–$0.015 per query
Deep research: ~$0.015–$0.03+ per query
Pro users get $5/month credits in Perplexity Pro subscription

Use reasoning/research models judiciously. Default to sonar for most queries.

List Available Models

scripts/perplexity_search.sh --list-models

Troubleshooting

Error: PERPLEXITY_API_KEY environment variable not set

Set up API key as described in "Setup Requirements" above

Error: curl command not found

Install curl: apt install curl or equivalent for your system

Error: Unexpected API response

Check your API key is valid and has not been revoked
Verify your Perplexity account has API access

Resources

scripts/

perplexity_search.sh - Main script for Perplexity API interactions
- Supports all Perplexity models
- Handles API key discovery from environment or config
- Provides multiple output formats
- Uses curl for API calls (no Python dependencies)

Note: This skill uses external API calls. Be mindful of rate limits and costs. The API key should never be committed to version control or shared publicly.