pplx-zero 1.1.6 → 1.1.8

package/README.md

@@ -1,404 +1,546 @@
-# PPLX-Zero
+# PPLX‑Zero
 
-> Fast Perplexity AI search CLI - minimal setup, maximal results
+🚀 **Lightning-fast Perplexity AI in your terminal** — sub‑1s search responses with multimodal support. Built for developers, coding agents, and automation workflows that demand speed and reliability.
 
-<p align="center">
-  <a href="https://badge.fury.io/js/pplx-zero"><img src="https://badge.fury.io/js/pplx-zero.svg" alt="npm version"></a>
-  <a href="https://aur.archlinux.org/packages/pplx-zero"><img src="https://img.shields.io/aur/version/pplx-zero?style=flat-square" alt="AUR package"></a>
-  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white" alt="TypeScript"></a>
-  <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-black?logo=bun&logoColor=white" alt="Bun"></a>
-  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
-</p>
+Perfect for rapid research, document analysis, image understanding, and batch processing with minimal configuration.
 
-A fast TypeScript CLI for Perplexity AI search with multimodal support. Built with Bun runtime for performance and reliability.
-
-## Features
+---
 
-- **⚡ Fast Search** - Concurrent queries with intelligent rate limiting
-- **🎯 Simple Setup** - Works with just an API key, no configuration required
-- **📦 Batch Processing** - Handle multiple searches simultaneously
-- **🔄 Real-time Updates** - JSONL streaming progress events
-- **🖼️ File Analysis** - Process documents and images with AI models
-- **🤖 AI Models** - Sonar, Sonar Pro, Sonar Deep Research, Sonar Reasoning
-- **🛡️ Type Safe** - Full Zod validation and TypeScript support
-- **🌍 Cross-Platform** - Native Bun runtime support
-- **🔄 Auto-Update** - Background update checking to stay current
+## ✨ What Makes PPLX‑Zero Special
 
-## Quick Start
+- **⚡ Blazing Fast**: Get answers in under a second with optimized API calls
+- **🧠 Smart Models**: Choose from Sonar, Sonar‑Pro, Sonar‑Reasoning, and Deep‑Research models
+- **📎 Multimodal**: Analyze documents, images, and combinations seamlessly
+- **🔄 Auto‑Update**: Stay current with simplified update management
+- **⚙️ Developer‑First**: Built for CI/CD, agent pipelines, and programmatic use
+- **🎯 Minimal Setup**: One environment variable and you're ready to go
 
-### 1️⃣ Install
+## 📦 Installation
 
-**📦 Package Manager Installation (Recommended)**
+Choose the installation method that works best for you:
 
-<p align="center">
-  <a href="https://badge.fury.io/js/pplx-zero"><img src="https://badge.fury.io/js/pplx-zero.svg" alt="npm version"></a>
-  <a href="https://aur.archlinux.org/packages/pplx-zero"><img src="https://img.shields.io/aur/version/pplx-zero?style=flat-square" alt="AUR package"></a>
-</p>
+### 🚀 Quick Install (Recommended)
 
 ```bash
-# npm (Node.js package manager) - Global installation
+# npm or bun (global)
 npm install -g pplx-zero
+# or
+bun install -g pplx-zero
+
+# Verify installation
+pplx --version
+```
+
+### 📦 Binary Download (No Node.js required)
+
+```bash
+# Download the appropriate binary for your platform
+# Linux (x64) - Most servers and desktops
+wget https://github.com/codewithkenzo/pplx-zero/releases/latest/download/pplx-v1.1.7-linux-x64
+chmod +x pplx-v1.1.7-linux-x64
+sudo mv pplx-v1.1.7-linux-x64 /usr/local/bin/pplx
+
+# Linux (ARM64) - Raspberry Pi, ARM servers
+wget https://github.com/codewithkenzo/pplx-zero/releases/latest/download/pplx-v1.1.7-linux-arm64
+chmod +x pplx-v1.1.7-linux-arm64
+sudo mv pplx-v1.1.7-linux-arm64 /usr/local/bin/pplx
+
+# macOS (Intel) - Macs with Intel processors
+wget https://github.com/codewithkenzo/pplx-zero/releases/latest/download/pplx-v1.1.7-darwin-x64
+chmod +x pplx-v1.1.7-darwin-x64
+sudo mv pplx-v1.1.7-darwin-x64 /usr/local/bin/pplx
+
+# macOS (Apple Silicon) - Macs with M1/M2/M3 chips
+wget https://github.com/codewithkenzo/pplx-zero/releases/latest/download/pplx-v1.1.7-darwin-arm64
+chmod +x pplx-v1.1.7-darwin-arm64
+sudo mv pplx-v1.1.7-darwin-arm64 /usr/local/bin/pplx
+
+# Windows (x64) - Most Windows computers
+# Download pplx-v1.1.7-windows-x64.exe from GitHub releases
+# Add to your PATH or run directly
+```
+
+**Alternative Installation Script (Linux/macOS):**
+
+```bash
+# Automated installation script
+curl -sSL https://github.com/codewithkenzo/pplx-zero/releases/latest/download/pplx-v1.1.7-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/x64/') -o pplx
+chmod +x pplx
+sudo mv pplx /usr/local/bin/pplx
+```
+
+### 🏛️ AUR (Arch Linux)
 
-# AUR (Arch Linux) - Binary package
+```bash
+# Using yay (recommended)
 yay -S pplx-zero
 
-# AUR (Arch Linux) - Manual build
-git clone https://aur.archlinux.org/pplx-zero.git
-cd pplx-zero
-makepkg -si
+# Using paru
+paru -S pplx-zero
 
 # Verify installation
 pplx --version
 ```
 
-**🔨 Manual Installation**
+### 🔧 Build from Source
 
 ```bash
-# Clone and build locally
+# 1) Clone the repository
 git clone https://github.com/codewithkenzo/pplx-zero.git
 cd pplx-zero
+
+# 2) Install dependencies and build
 bun install && bun run build
 
-# Add to PATH
-sudo ln -s "$(pwd)/dist/cli.js" /usr/local/bin/pplx
+# 3) Link the CLI (system-wide)
+sudo ln -s "$(pwd)/dist/index.js" /usr/local/bin/pplx
 
-# Verify installation
+# 4) Verify installation
 pplx --version
 ```
 
-### 2️⃣ Setup API Key
+---
+
+## ⚙️ Configuration
+
+### API Key Setup
+
+Set your Perplexity API key as an environment variable:
 
 **Linux/macOS:**
 ```bash
+# Temporary (current session)
 export PERPLEXITY_API_KEY="your-api-key"
+
+# Permanent (add to ~/.bashrc, ~/.zshrc, etc.)
+echo 'export PERPLEXITY_API_KEY="your-api-key"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Windows (PowerShell):**
+```powershell
+# Temporary (current session)
+$env:PERPLEXITY_API_KEY = "your-api-key"
+
+# Permanent
+[Environment]::SetEnvironmentVariable("PERPLEXITY_API_KEY", "your-api-key", "User")
 ```
 
-**Windows:**
+**Windows (CMD):**
 ```cmd
+# Permanent
 setx PERPLEXITY_API_KEY "your-api-key"
 ```
 
-**Get your API key:** https://www.perplexity.ai/account/api/keys
-
-### 3️⃣ Start Searching
-
-```bash
-# Simple search
-pplx "latest AI developments"
+> 🔑 **Get your API key** from your [Perplexity account settings](https://www.perplexity.ai/settings/api) and keep it secure. Never share your API key or commit it to version control.
 
-# Choose model for detailed analysis
-pplx --model sonar-pro "Explain quantum computing"
+---
 
-# Analyze document
-pplx --file report.pdf "Summarize this document"
+## 🔄 Auto‑Update Management
 
-# Analyze image
-pplx --image screenshot.png "What does this interface do?"
+PPLX‑Zero includes a simplified auto‑update system that keeps you current with the latest features and security updates.
 
-# Document + image analysis
-pplx --file data.csv --image chart.png "Analyze this data"
+### Basic Update Commands
 
-# Advanced AI models
-pplx --model sonar-reasoning "Solve this math problem"
-pplx --model sonar-deep-research "History of artificial intelligence"
+```bash
+# Check for available updates
+pplx update --check
 
-# See basic help
-pplx --help
+# Install updates and relaunch automatically
+pplx update --auto
 ```
 
-## Auto-Update
-
-PPLX-Zero includes intelligent auto-update functionality that runs in the background to keep your CLI current.
+### Update Workflow
 
-### How It Works
+1. **Automatic Notifications**: PPLX‑Zero checks for updates once per day and notifies you when a new version is available
+2. **Smart Installation**: The updater detects your installation method (npm, AUR, binary) and uses the appropriate update mechanism
+3. **Seamless Relaunch**: When using `--auto`, PPLX‑Zero installs the update and relaunches with your original command
 
-- **Background Checking**: Automatically checks for updates every 24 hours when you run searches
-- **Non-Blocking**: Never slows down your search queries - updates happen in the background
-- **Smart Caching**: Uses intelligent caching to avoid unnecessary network requests
-- **Silent by Default**: Runs quietly without interrupting your workflow
-
-### Update Commands
+### Advanced Update Options
 
 ```bash
-# Check for updates manually
+# Force update check (ignores cache)
 pplx update --check
 
-# Install available updates automatically
-pplx update --auto
+# Update during automation without interaction
+pplx update --auto --quiet
+```
 
-# Show version information
-pplx version
+### Troubleshooting Updates
 
-# Check updates with version command
-pplx version --check-updates
-```
+| Issue | Solution |
+|-------|----------|
+| **Permission denied** | Run with `sudo` or check installation directory permissions |
+| **Network timeout** | Check internet connection and try again |
+| **Update fails** | Manually install using your original installation method |
+| **Lock file error** | Wait for current update to complete or manually remove `~/.pplx-zero/.updating.lock` |
 
-### Update Methods
+The auto‑update system respects your system configuration and won't modify files without proper permissions.
 
-The auto-update system tries multiple package managers in order of preference:
+---
 
-1. **npm global** (`npm update -g pplx-zero`)
-2. **bun global** (`bun update -g pplx-zero`)
-3. **yarn global** (`yarn global upgrade pplx-zero`)
-4. **pnpm global** (`pnpm update -g pplx-zero`)
+## 🚀 Quick Examples
 
-If automatic updates fail, you'll get helpful instructions to update manually.
+### Basic Search
 
-### Configuration
+```bash
+# Simple search (default model: sonar)
+pplx "python type hints best practices"
 
-Auto-update settings are stored in `~/.pplx-zero/update-cache.json`:
+# Multiple queries in one command
+pplx "React hooks tutorial" "TypeScript generics" "Docker best practices"
+```
 
-- **Check Interval**: 24 hours by default
-- **Quiet Mode**: Silent operation to not interrupt workflow
-- **Auto Install**: Disabled by default for safety
+### Advanced Models
 
-### Privacy & Performance
+```bash
+# Research with Sonar Pro (more detailed analysis)
+pplx -m sonar-pro "React 19 Hooks new features"
 
-- **Minimal Network**: Only checks npm registry for version information
-- **No Data Collection**: Never sends search queries or personal data
-- **Fast Performance**: Cached results prevent repeated network requests
-- **Local Only**: All update logic runs locally on your machine
+# Deep research with comprehensive web context
+pplx -m sonar-deep-research "best Rust web frameworks 2025"
 
-## Usage Guide
+# Mathematical reasoning and proofs
+pplx -m sonar-reasoning "prove this algorithm runs in O(n log n)"
+```
 
-### Command Line Options
+### Document & Image Analysis
 
-**Quick Reference:**
 ```bash
-# Basic search
-pplx "latest AI developments"
+# Summarize a PDF report quickly
+pplx -f report.pdf "summarize key findings and risks"
 
-# File analysis (simplified)
-pplx -f document.pdf "Summarize this"
+# Understand an interface from a screenshot
+pplx -i screenshot.png "what is this UI and what are the next steps?"
 
-# Advanced batch processing
-pplx --input queries.json -c 10 -t 60000
+# Combine multiple files in one analysis
+pplx -f data.csv -i chart.png "spot anomalies and explain the chart"
 
-# See all options
-pplx --help
-```
+# Multiple file attachments
+pplx -f report.pdf --attach data.csv --attach summary.md "analyze all documents"
 
-**Essential Commands:**
-```bash
-# Model selection
-pplx -m sonar-pro "Detailed analysis"
+# Multiple documents of same type using --attach
+pplx --attach doc1.pdf --attach doc2.pdf --attach doc3.txt "compare all reports"
 
-# File + image
-pplx -f doc.md -i chart.png "Analyze both"
+# Multiple images using --attach-image
+pplx --attach-image screenshot1.png --attach-image screenshot2.png "analyze the UI flow"
 
-# Output format
-pplx -o jsonl "Get streaming output"
+# Mixed multiple files (documents + images)
+pplx -f main.pdf --attach appendix.md --attach-image chart.png --attach-image diagram.jpg "comprehensive analysis"
 
-# Async with webhook
-pplx --async --webhook https://api.example.com "Long task"
+# Multiple files with positional arguments (all treated as files)
+pplx file1.pdf file2.txt file3.md "what's in these files"
 ```
 
 ### Batch Processing
 
-Create `queries.json`:
+```bash
+# Stream newline-delimited JSON for agents or UNIX pipes
+pplx -o jsonl "AI trends"
 
+# Batch from a JSON file with custom concurrency
+pplx -I queries.json -o jsonl -c 5 -t 30000
+```
+
+**Batch JSON format:**
 ```json
 {
   "version": "1.0.0",
   "requests": [
-    {"op": "search", "args": {"query": "AI trends", "maxResults": 5}},
-    {"op": "search", "args": {"query": "TypeScript patterns", "maxResults": 3}},
-    {"op": "search", "args": {"query": "Bun performance", "maxResults": 3}}
+    { "op": "search", "args": { "query": "AI trends", "maxResults": 5 } },
+    { "op": "search", "args": { "query": "TypeScript patterns", "maxResults": 3 } }
   ],
-  "options": {
-    "concurrency": 5,
-    "timeoutMs": 30000
-  }
+  "options": { "concurrency": 5, "timeoutMs": 30000 }
 }
 ```
 
-Process with:
+### Advanced Workflows
+
+```bash
+# Fire-and-forget async with webhook callback
+pplx --async --webhook http://localhost:3000/callback "long research task"
+
+# Export results to file
+pplx --export results.json "machine learning trends"
+
+# Search with custom result limits
+pplx -n 10 "latest web development frameworks"
+
+# Query from stdin (for pipelines)
+echo '{"query": "best practices for API design"}' | pplx -s
+```
+
+### Real‑World Scenarios
 
 ```bash
-pplx --input queries.json --format jsonl
+# Security researcher: Analyze vulnerability report
+pplx -f vuln_report.pdf --attach screenshots/ "explain security implications"
+
+# Data analyst: Extract insights from datasets
+pplx -f sales_data.csv -i revenue_chart.png "identify growth opportunities"
+
+# Developer: Code review and optimization
+pplx -f app.py --attach perf_metrics.json "suggest performance improvements"
+
+# Product manager: Competitive analysis
+pplx -f competitor_data.pdf "summarize key differentiators and market position"
 ```
 
-### File Attachments
 
-Supported file formats for analysis:
+---
 
-**Documents (max 50MB):**
+## 📋 Command Reference
+
+### Main Options
+
+| Flag | Short | Description | Example |
+|------|-------|-------------|---------|
+| `--model` | `-m` | AI model to use | `-m sonar-pro` |
+| `--max-results` | `-n` | Max results per query (1-20) | `-n 10` |
+| `--file` | `-f` | Attach document for analysis | `-f report.pdf` |
+| `--image` | `-i` | Attach image for analysis | `-i screenshot.png` |
+| `--format` | `-o` | Output format: json/jsonl | `-o jsonl` |
+| `--query` | `-q` | Search query (alternative to positional) | `-q "search term"` |
+| `--export` | | Export results to file | `--export results.json` |
+| `--input` | `-I` | Read queries from JSON file | `-I batch.json` |
+| `--stdin` | `-s` | Read queries from stdin | `cat query.json \| pplx -s` |
+| `--attach` | | Additional file attachments | `--attach file1.pdf --attach file2.txt` |
+| `--attach-image` | | Additional image attachments | `--attach-image img1.png --attach-image img2.jpg` |
+| `--async` | | Enable async mode for advanced models | `--async` |
+| `--webhook` | | Webhook URL for async results | `--webhook http://localhost:3000` |
+| `--workspace` | | Workspace directory for file operations | `--workspace ./project` |
+| `--use-search-api` | | Use search API (default: true) | `--use-search-api` |
+| `--batch-size` | | Batch size for processing (1-100) | `--batch-size 50` |
+
+### Performance & Control
+
+| Flag | Description | Default | Range |
+|------|-------------|---------|-------|
+| `--concurrency` | Max parallel requests for batch operations | 5 | 1-20 |
+| `--timeout` | Request timeout in milliseconds | 30000 | 1000-300000 |
+
+### Utility Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `update --check` | Check for available updates | `pplx update --check` |
+| `update --auto` | Install updates and relaunch | `pplx update --auto` |
+| `history [limit]` | Show search history | `pplx history 10` |
+| `version` | Show version information | `pplx version` |
+| `--help` | Show help message | `pplx --help` |
+| `--version` | Show version number | `pplx --version` |
+
+### Supported File Formats
+
+**Documents (up to 50MB):**
 - PDF, DOC, DOCX, TXT, RTF, MD
+- CSV, JSON (structured data)
+- XML, YAML (configuration files)
 
-**Images (max 50MB):**
-- PNG, JPEG, WebP, HEIF, HEIC, GIF
+**Images (up to 50MB):**
+- PNG, JPEG, WebP, HEIF/HEIC, GIF
+- BMP, TIFF (legacy formats)
 
-**Examples:**
-```bash
-# Document analysis
-pplx --attach report.pdf "Summarize this document"
+### AI Models
+
+| Model | Best For | Speed | Detail |
+|-------|----------|-------|--------|
+| `sonar` | Quick answers, general queries | ⚡ Fast | Standard detail |
+| `sonar-pro` | Detailed analysis, research | 🚀 Fast | Enhanced detail |
+| `sonar-reasoning` | Mathematical reasoning, logic | 🐢 Moderate | Step-by-step |
+| `sonar-deep-research` | Comprehensive research with web context | 🐌 Slow | Maximum detail |
+
+---
+
+## 💻 Programmatic Use
+
+### TypeScript API
+
+Use the toolkit directly in TypeScript when embedding into agents or services.
+
+```ts
+import { PerplexitySearchTool } from 'pplx-zero';
+
+// Initialize the search tool
+const tool = new PerplexitySearchTool();
 
-# Image analysis
-pplx --attach-image screenshot.png "Analyze this interface"
+// Single search query
+const result = await tool.search({
+  query: "TypeScript best practices",
+  model: "sonar-pro",
+  maxResults: 5
+});
 
-# Multiple files
-pplx --attach document.txt --attach-image chart.png "Analyze this data"
+console.log(result);
 ```
 
-### Programmatic Usage
+### Batch Processing
 
-```typescript
+```ts
 import { PerplexitySearchTool } from 'pplx-zero';
 
 const tool = new PerplexitySearchTool();
 
-const result = await tool.runBatch({
+// Batch search with custom configuration
+const batchResult = await tool.runBatch({
   version: "1.0.0",
-  requests: [{
-    op: "search",
-    args: { query: "TypeScript best practices", maxResults: 5 }
-  }]
+  requests: [
+    {
+      op: "search",
+      args: {
+        query: "TypeScript best practices",
+        maxResults: 5,
+        model: "sonar-pro"
+      }
+    },
+    {
+      op: "search",
+      args: {
+        query: "React performance optimization",
+        maxResults: 3,
+        model: "sonar"
+      }
+    }
+  ],
+  options: {
+    concurrency: 3,
+    timeoutMs: 30000
+  }
 });
 
-console.log(result);
+console.log('Batch results:', batchResult);
 ```
 
-## Configuration
-
-### Simplified Options (Everyday Usage)
-
-| Option | Short | Type | Default | Description |
-|--------|-------|------|---------|-------------|
-| `--file` | `-f` | string | - | Attach document (PDF, DOC, DOCX, TXT, RTF, MD) |
-| `--image` | `-i` | string | - | Attach image (PNG, JPEG, WebP, HEIF, HEIC, GIF) |
-| `--format` | `-o` | string | json | Output format: json|jsonl |
-| `--model` | `-m` | string | sonar | AI model: sonar, sonar-pro, sonar-deep-research, sonar-reasoning |
-| `--version` | `-v` | boolean | - | Show version |
-| `--help` | `-h` | boolean | - | Show basic help |
-
-### Update Commands
-
-| Command | Options | Description |
-|---------|---------|-------------|
-| `pplx update` | `--check` | Check for available updates |
-| `pplx update` | `--auto` | Install available updates automatically |
-| `pplx version` | `--check-updates` | Show version and check for updates |
-| `pplx version` | `--verbose` | Show detailed version information |
-
-### Advanced Options (Power Users)
-
-| Option | Short | Type | Default | Description |
-|--------|-------|------|---------|-------------|
-| `--input` | `-I` | string | - | Read batch requests from JSON file |
-| `--stdin` | `-s` | boolean | false | Read JSONL requests from stdin |
-| `--concurrency` | `-c` | number | 5 | Max concurrent requests (1-20) |
-| `--timeout` | `-t` | number | 30000 | Request timeout in ms (1000-300000) |
-| `--workspace` | `-w` | string | - | Workspace directory for sandboxing |
-| `--attach` | - | string[] | - | Attach document files (multiple) |
-| `--attach-image` | - | string[] | - | Attach image files (multiple) |
-| `--async` | - | boolean | false | Process requests asynchronously |
-| `--webhook` | - | string | - | Webhook URL for async notifications |
- |
-
-### Quick Reference
+### Advanced Usage with Error Handling
 
-```bash
-# Basic usage (simplified)
-pplx -f doc.pdf -m sonar-pro "analyze this"
+```ts
+import { PerplexitySearchTool } from 'pplx-zero';
 
-# Advanced usage (full control)
-pplx -I batch.json -c 10 -t 60000 --format jsonl "process all"
+async function searchWithRetry(query: string, maxRetries = 3) {
+  const tool = new PerplexitySearchTool();
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const result = await tool.search({
+        query,
+        model: "sonar-pro",
+        maxResults: 5
+      });
+
+      return result;
+    } catch (error) {
+      if (attempt === maxRetries) {
+        throw new Error(`Search failed after ${maxRetries} attempts: ${error}`);
+      }
+
+      // Exponential backoff
+      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
+    }
+  }
+}
 
-# See all available options
-pplx --help
+// Usage
+searchWithRetry("latest AI trends")
+  .then(result => console.log(result))
+  .catch(error => console.error(error));
 ```
 
-### AI Models
+---
 
-- `sonar` - Fast, concise responses (default)
-- `sonar-pro` - Detailed, comprehensive responses
-- `sonar-deep-research` - In-depth research with web search
-- `sonar-reasoning` - Step-by-step logical reasoning
+## 🛠️ Troubleshooting
 
-## Output Formats
+### Common Issues & Solutions
 
-### JSON (Default)
-```json
-{
-  "version": "1.0.0",
-  "ok": true,
-  "summary": {
-    "total": 1,
-    "successful": 1,
-    "failed": 0,
-    "totalDuration": 572
-  },
-  "results": [...]
-}
+#### API Key Problems
+```bash
+# Error: "API key not found"
+export PERPLEXITY_API_KEY="your-api-key"
+
+# Verify key is set
+echo $PERPLEXITY_API_KEY
 ```
 
-### JSONL (Streaming)
+#### File Attachment Issues
 ```bash
-pplx --format jsonl "AI trends"
+# Error: "File too large" (files must be < 50MB)
+ls -lh your-file.pdf
+
+# Supported formats check
+file your-document.pdf  # Should show PDF format
 ```
-Each result printed as a separate JSON line for real-time processing.
 
-## Development
+#### Network/Timeout Issues
+```bash
+# Increase timeout for complex queries
+pplx -t 60000 "complex research question"
 
+# Check internet connectivity
+curl -I https://api.perplexity.ai
+```
+
+#### Permission Issues
 ```bash
-# Clone and build
-git clone https://github.com/codewithkenzo/pplx-zero.git
-cd pplx-zero
-bun install && bun run build
+# Permission denied during installation
+npm install -g pplx-zero --unsafe-perm
 
-# Development mode
-bun run dev
+# Or use npx to avoid global installation
+npx pplx-zero "your query"
+```
 
-# Type checking
-bun run typecheck
+### Debug Mode
 
-# Build for production
-bun run build
+```bash
+# Enable verbose output for debugging
+DEBUG=pplx:* pplx "your query"
 
-# Create binary
-bun run build:binary
+# Check configuration
+pplx --version
+pplx update --check
 ```
 
-## Architecture
+### Performance Tips
 
-- **Bun Runtime** - Fast JavaScript runtime
-- **Zod Validation** - Type-safe schema validation
-- **Error Handling** - Resilient error recovery
-- **Concurrency Control** - Semaphore pattern for rate limiting
-- **Streaming Events** - Real-time progress updates
+| Scenario | Recommended Settings |
+|----------|---------------------|
+| **Quick searches** | Default settings (sonar model) |
+| **Deep research** | `-m sonar-deep-research -t 60000` |
+| **Batch processing** | `-c 10 -t 45000` |
+| **File analysis** | `-m sonar-pro -t 60000` |
+| **Real-time queries** | `-m sonar -n 3` |
 
-## Security Features
+---
 
-- Environment variable API key management
-- Input validation and sanitization
-- Request timeout protection
-- Error information filtering
-- No external dependencies beyond core runtime
+## 📚 Additional Resources
 
-## Error Handling
+- **GitHub Repository**: [github.com/codewithkenzo/pplx-zero](https://github.com/codewithkenzo/pplx-zero)
+- **Bug Reports & Issues**: [GitHub Issues](https://github.com/codewithkenzo/pplx-zero/issues)
+- **Perplexity API Documentation**: [docs.perplexity.ai](https://docs.perplexity.ai)
+- **Model Comparison**: Detailed model comparison in the [AI Models](#ai-models) section above
 
-PPLX-Zero provides comprehensive error classification:
+---
 
-```typescript
-enum ErrorCode {
-  VALIDATION_ERROR = "VALIDATION_ERROR",
-  API_KEY_MISSING = "API_KEY_MISSING",
-  API_ERROR = "API_ERROR",
-  TIMEOUT_ERROR = "TIMEOUT_ERROR",
-  NETWORK_ERROR = "NETWORK_ERROR",
-  RATE_LIMIT_ERROR = "RATE_LIMIT_ERROR",
-  UNEXPECTED_ERROR = "UNEXPECTED_ERROR"
-}
-```
+### Quick Reference Commands
+
+```bash
+# Show all available options
+pplx --help
 
-## Contributing
+# Check for updates
+pplx update --check
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+# Auto-update
+pplx update --auto
 
-## License
+# Show version
+pplx --version
+
+# Search history
+pplx history 10
 
-MIT License - see [LICENSE](LICENSE) file for details.
+# Quick test
+pplx "test query"
+```
 
 ---
 
-**Built with [Bun](https://bun.sh) and [Perplexity AI](https://www.perplexity.ai)**
+*Built with ❤️ using [Bun](https://bun.sh) and powered by [Perplexity AI](https://www.perplexity.ai)*