searchctl CLI redesign analysis for Perplexity API

searchctl-redesign.md

searchctl CLI Redesign Analysis

Analysis Summary

Current searchctl Issues

1. Confusing default behavior - Default query uses chat completions; raw is a hidden subcommand
2. Flag overload - 15+ flags mixed together (model, context, mode, domains, dates, effort, media, etc.)
3. Model complexity hidden - Four distinct models with different capabilities collapsed into one flag
4. Pro Search absent - The new search_type: pro/auto feature isn't exposed
5. No clear cost/capability signaling - Users don't know if they're using $0.005 or $1.30 per query

Perplexity API Surface

Endpoint	Purpose	Models/Features
/chat/completions	AI-grounded answers	sonar, sonar-pro, sonar-reasoning-pro
/chat/completions + Pro Search	Multi-step reasoning	sonar-pro with search_type: pro/auto
/async/chat/completions	Deep research	sonar-deep-research (polling)
/search	Raw ranked results	No AI, just search index

Key Design Principles from Other CLIs

• packagectl: Verb-oriented by capability (code-grep, semantic-grep, research-package)
• knowctl: Resource + action (list-topics, show-document, semantic-search)
• codectl: Action-oriented (search-text, extract-symbols, find-dependencies)

---

Design Approaches

Approach A: API-Aligned (Endpoints → Subcommands)

searchctl chat <query>           # Chat completions API (default: sonar-pro)
searchctl search <query>         # Search API (raw results)
searchctl async <query>          # Async API (deep research)
searchctl models                 # List available models

Options flow naturally from API:

searchctl chat "quantum computing" --model sonar-reasoning-pro --context high
searchctl chat "SEC filings NVDA" --mode sec --domains sec.gov
searchctl search "AI news" --max-results 20 --recency week
searchctl async "market analysis 2025" --effort high

Pros: 1:1 API mapping, predictable, easy to document
Cons: "chat" is awkward for agents, "async" is implementation detail

---

Approach B: Intent/Level-Based (Query Complexity)

Organize by reasoning depth and use case:

searchctl quick <query>      # sonar (fast, cheap, ~$0.006/query)
searchctl answer <query>     # sonar-pro (balanced, ~$0.01/query)  
searchctl reason <query>     # sonar-reasoning-pro (multi-step)
searchctl research <query>   # sonar-deep-research (exhaustive, ~$0.40-1.30/query)
searchctl raw <query>        # Search API (no AI, $0.005/query)

Examples:

searchctl quick "What is the capital of France?"
searchctl answer "Compare Tesla Model 3 vs Rivian R1T" --context high
searchctl reason "Analyze the trade-offs of microservices vs monolith"
searchctl research "Comprehensive analysis of quantum computing impact on cryptography"
searchctl raw "AI regulations 2025" --max-results 20

Pros: Intuitive task mapping, clear cost/capability progression, agent-friendly
Cons: Model names hidden, "quick" naming could be clearer

---

Approach C: Model-as-Subcommand

Models become first-class subcommands:

searchctl sonar <query>           # Lightweight search
searchctl sonar-pro <query>       # Advanced search
searchctl sonar-pro <query> --pro # Pro Search (multi-step tools)
searchctl reasoning <query>       # Reasoning model
searchctl deep <query>            # Deep research (async)
searchctl search <query>          # Raw search API
searchctl models                  # List models with descriptions

Examples:

searchctl sonar "latest news on SpaceX"
searchctl sonar-pro "quantum computing advances" --context high --mode academic
searchctl sonar-pro "compare EV manufacturers 2025" --pro  # enables tool usage
searchctl reasoning "analyze the logic in this argument about AI safety"
searchctl deep "comprehensive report on renewable energy policy" --effort high
searchctl search "python web frameworks" --domains github.com,pypi.org

Pros: Explicit model selection, clear capability mapping
Cons: Many subcommands, model names may change

---

Approach D: Task-Oriented (Agent-Optimized)

Focus on what agents actually need:

searchctl find <query>       # Quick fact lookup (sonar)
searchctl ask <query>        # Q&A with citations (sonar-pro)
searchctl analyze <query>    # Complex reasoning (sonar-reasoning-pro)
searchctl research <query>   # Deep research report (sonar-deep-research)
searchctl sources <query>    # Raw sources only (search API)
searchctl models             # Show model details and pricing

Examples:

searchctl find "current Bitcoin price"
searchctl ask "How does OAuth2 work?" --context high
searchctl analyze "What are the implications of the EU AI Act for startups?"
searchctl research "State of AI in healthcare 2025" --effort high
searchctl sources "climate change research 2024" --domains nature.com,science.org

Pros: Very intuitive, natural language task names, agent-friendly
Cons: Model mapping not obvious to API-familiar users

---

Recommendation: Hybrid of B + C

Combine intent-based naming with explicit model access:

# Primary interface (intent-based, recommended for agents)
searchctl quick <query>       # → sonar
searchctl ask <query>         # → sonar-pro (default)
searchctl reason <query>      # → sonar-reasoning-pro  
searchctl research <query>    # → sonar-deep-research

# Raw search (no AI)
searchctl raw <query>

# Model info
searchctl models

# Expert mode: direct model access (hidden/advanced)
searchctl --model sonar-pro <query>

Key design decisions:

1. Default command is ask - Most common use case, agents can just run searchctl ask "..."

2. Pro Search via flag - searchctl ask "..." --pro or searchctl ask "..." --auto

3. Filters as consistent flags across all commands:

   --context low|medium|high     # Search context size
   --mode web|academic|sec       # Search mode
   --domains example.com,...     # Allowlist domains  
   --exclude reddit.com,...      # Denylist domains
   --recency day|week|month|year # Time filter
   --after MM/DD/YYYY            # Published after
   --before MM/DD/YYYY           # Published before
   

4. YAML output with consistent structure:

   query: "your question"
   model: sonar-pro
   answer: "The response..."
   citations:
     - title: "Source 1"
       url: "https://..."
   usage:
     input_tokens: 150
     output_tokens: 500
     cost: "$0.012"

5. Cost shown in output - Agents can track spend