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 requires Perplexity API key via environment variable:

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

Note: Do not store API key in Clawdbot config. The skill only reads from environment variable to avoid config conflicts.

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.