searchctl v2 redesign summary - compound subcommands for Perplexity API

searchctl-v2-summary.md

searchctl v2 - Redesigned CLI for Perplexity API

New Subcommands

Command	Model	Use Case	Cost
quick-search	sonar	Fast facts, simple Q&A	~$0.006/query
web-search	sonar-pro	Grounded Q&A with citations	~$0.01/query
pro-search	sonar-pro + Pro Search	Multi-step reasoning with tools	~$0.015-0.025/query
reason-search	sonar-reasoning-pro	Complex reasoning and analysis	~$0.01/query
deep-research	sonar-deep-research	Exhaustive research reports	~$0.40-1.30/query
raw-search	Search API	Raw results without AI	$5/1K requests
list-models	-	Show models with pricing	-

Examples

# Quick fact lookup (sonar, ~$0.006/query)
searchctl quick-search "What is the capital of France?"

# Standard grounded Q&A (sonar-pro, ~$0.01/query)
searchctl web-search "Compare React vs Vue for large applications" --context high

# Multi-step tool usage for complex queries (sonar-pro + Pro Search)
searchctl pro-search "Analyze Tesla's Q3 2024 earnings vs competitors"

# Academic research with reasoning (sonar-reasoning-pro)
searchctl reason-search "What are the logical implications of Gödel's incompleteness theorems?" --mode academic

# Exhaustive research report (sonar-deep-research, ~$0.40-1.30/query)
searchctl deep-research "Comprehensive analysis of quantum computing impact on cryptography" --effort high

# Raw sources without AI synthesis (search API, $0.005/query)
searchctl raw-search "climate change research 2024" --domains nature.com,science.org --max-results 20

Consistent Flags

All AI-powered commands share these flags:

-c, --context {low,medium,high}   Search context size (default: medium)
--mode {web,academic,sec}         Search mode (default: web)
-d, --domains DOMAINS             Allowlist domains (comma-separated)
--exclude EXCLUDE                 Denylist domains (comma-separated)
-r, --recency {day,week,month,year}  Time filter
--after AFTER                     Published after date (MM/DD/YYYY)
--before BEFORE                   Published before date (MM/DD/YYYY)

Additional flags:

• pro-search --auto - Auto-classify query complexity
• deep-research --effort {low,medium,high} - Research effort level
• raw-search --queries - Multi-query search (up to 5)
• raw-search --country - Geographic filtering
• raw-search --language - Language filtering

YAML Output Structure

query: "your question"
model: sonar-pro
search_type: pro  # only for pro-search
answer: "The synthesized response..."
citations:
  - title: "Source Title"
    url: "https://example.com/article"
    date: "2024-03-15"
usage:
  input_tokens: 150
  output_tokens: 500
  total_tokens: 650
  estimated_cost: "$0.0120"

New Features

• Pro Search support - Multi-step reasoning with web_search and fetch_url_content tools
• Cost estimation - Every response includes usage.estimated_cost
• Streaming support - Pro Search uses streaming for real-time responses
• Multi-query support - raw-search can batch up to 5 queries
• Comprehensive pricing - list-models shows all pricing tiers