Perplexity CLI

A beautiful, feature-rich command-line interface for the Perplexity AI API with interactive arrow navigation — Cross-platform (Linux, macOS, Windows)

✨ Features

• Beautiful Terminal UI - ASCII art "PERPLEXITY CLI" banner, colored output, status bars, and formatted messages
• Arrow Navigation Menus - Interactive settings and model selection with ↑↓ keys
• Interactive Chat Mode - Full REPL with slash commands and conversation history
• Markdown Formatting - Supports bold, italic, code blocks, headers, and lists
• Rich Text Output - Syntax highlighting, colored code blocks, and styled links
• Real-time Streaming - Watch answers generate with proper word wrapping
• Conversation Persistence - Save/load chats and export to Markdown
• Custom System Prompts - Create custom AI personas
• Citations Support - View source citations for research answers
• Secure API Keys - .env file support for secure API key management

🚀 Quick Start

Linux / macOS

# Install dependencies
pip install openai python-dotenv

# Copy the script
cp perplexity ~/.local/bin/perplexity
chmod +x ~/.local/bin/perplexity

# Add to PATH (if not already)
export PATH="$HOME/.local/bin:$PATH"

# Start chatting!
perplexity --chat

Windows (PowerShell)

# Install dependencies
pip install openai python-dotenv

# Copy the script to a folder in your PATH
# Common locations:
#   C:\Users\%USERNAME%\AppData\Local\Programs\Python\Python3xx\Scripts\
#   C:\Users\%USERNAME%\AppData\Local\Microsoft\WindowsApps\
Copy-Item perplexity $env:USERPROFILE\perplexity.py

# Create an alias (add to your PowerShell profile)
# Run `notepad $PROFILE` and add:
#   function perplexity { python $env:USERPROFILE\perplexity.py @args }

# Start chatting!
perplexity --chat

Windows (Command Prompt)

REM Install dependencies
pip install openai python-dotenv

REM Copy to a folder in PATH, e.g.:
COPY perplexity C:\Users\%USERNAME%\AppData\Local\Programs\Python\Python3xx\Scripts\perplexity.py

REM Create batch wrapper (one-time):
echo @python "%USERPROFILE%\perplexity.py" %* > C:\Windows\perplexity.bat

REM Start chatting!
perplexity --chat

⚙️ Setup

API Key

Get your API key from perplexity.ai/settings/api

Option 1: Environment Variable

export PERPLEXITY_API_KEY="your-api-key-here"

Option 2: .env File (Recommended)

Linux / macOS:

mkdir -p ~/.perplexity
cat > ~/.perplexity/.env << 'EOF'
PERPLEXITY_API_KEY=your-api-key-here
EOF

Windows (PowerShell):

New-Item -Path "$env:USERPROFILE\.perplexity" -ItemType Directory -Force
Set-Content -Path "$env:USERPROFILE\.perplexity\.env" -Value "PERPLEXITY_API_KEY=your-api-key-here"

Windows (Command Prompt):

mkdir "%USERPROFILE%\.perplexity"
echo PERPLEXITY_API_KEY=your-api-key-here > "%USERPROFILE%\.perplexity\.env"

📖 Usage

Interactive Chat

perplexity --chat      # or -c
perplexity --chat --stream
perplexity --chat --model sonar-medium-online
perplexity --chat --system "You are a sarcastic comedian"

Single Query

perplexity "What is the capital of France?"
perplexity "Explain quantum physics" --stream
perplexity "Latest AI news" --search
perplexity "Debug this code" --system "You are a Python expert"

🎮 Interactive Commands

Command	Description
/menu	⭐ Open interactive settings menu (arrow keys)
/model	Switch AI model with arrow selection
/help	Show interactive help box
/clear	Clear conversation history
/save	Save current conversation
/export	Export conversation to Markdown
/history	List all saved conversations
/load	Load a saved conversation
/status	Show current session info
/quit	Exit chat mode
/exit	Exit chat mode
/q	Exit chat mode

Keyboard Shortcuts:

• Ctrl+C - Interrupt current response
• Ctrl+D - Exit chat mode
• ↑↓ - Navigate menus
• ENTER - Select menu item
• ESC - Cancel/close menu

🔧 Options

Option	Short	Description	Default
query	-	Your question or search query	-
--chat	-c	Enter interactive chat mode	-
--model	-	Model to use	sonar-pro
--search	-	Use research-focused mode	-
--stream	-	Stream responses in real-time	-
--system	-s	Custom system prompt	-
--api-key	-	Override API key	-
--no-color	-	Disable colored output	-

🤖 Available Models

Model	Best For	Speed
sonar-pro	General queries with web citations	⭐⭐
sonar-medium-online	Faster responses	⭐⭐⭐
sonar-small-online	Quick answers	⭐⭐⭐⭐

💡 Examples

Quick Question

$ perplexity "What is the capital of Australia?"

┌─ Perplexity ───────────────────────────────────────
│ Canberra, located in the Australian Capital Territory.
└─────────────────────────────────────────────────────

Research with Citations

$ perplexity "Latest developments in AI agents" --search

┌─ Perplexity ───────────────────────────────────────
│ AI agents are evolving rapidly with new capabilities...

📚 Sources
  [1] https://perplexity.ai/blog/ai-agents
  [2] https://openai.com/research/agents
└─────────────────────────────────────────────────────

Custom Persona

$ perplexity -s "You are a sarcastic pirate captain" "Tell me a joke"

┌─ Perplexity ───────────────────────────────────────
│ Arrr, why did the pirate go to medical school?
│ Because he wanted to study "arrr-thritis", ye scallywag!
└─────────────────────────────────────────────────────

💾 Conversation History

Conversations are saved automatically to ~/.cache/perplexity/ as JSON files.

Managing Conversations

# List saved conversations
You: /history

📂 Saved Conversations
  • chat_20240203_153045.json (5 msgs) - 2024-02-03T15:30:45
  • chat_20240203_140000.json (12 msgs) - 2024-02-03T14:00:00

# Load a conversation
You: /load

[1] chat_20240203_153045.json (5 msgs)
[2] chat_20240203_140000.json (12 msgs)

Load which one? (number or 'cancel'): 1
✓ Loaded 5 messages.

# Export to Markdown
You: /export
Output filename (e.g. chat.md): my_research.md
✓ Exported to: my_research.md

🎨 Terminal Interface

Welcome Screen (v2.0)

   ██████╗ ███████╗██████╗ ██████╗ ███████╗
  ██╔════╝ ██╔════╝██╔══██╗██╔══██╗██╔════╝
  ██║  ███╗█████╗  ██████╔╝██████╔╝███████╗
  ██║   ██║██╔══╝  ██╔══██╗██╔══██╗╚════██║
  ╚██████╔╝███████╗██║  ██║██║  ██║███████║
   ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝
                  CLI v2.0

━━━  Model: SONAR PRO                    2024-02-03 03:30 PM  ━━━

  MENU OPTIONS:
  Type '/menu' to open settings
  Type '/help' for all commands

Quick Commands:
  /menu        Open settings menu (arrow navigation)
  /model       Switch AI model
  /clear       Clear conversation
  /save        Save conversation
  /export      Export to Markdown
  /history     List saved chats
  /load        Load saved chat
  /quit        Exit

Interactive Settings Menu

╔════════════════════════════════════════════════════════════════════════╗
║                        PERPLEXITY CLI • SETTINGS                  ║
╚════════════════════════════════════════════════════════════════════════╝

► 🤖 Change Model
  🔧 API Settings
  💾 Conversation History
  📤 Export Conversation
  ℹ️  About
  ← Back to Chat

  ↑↓ Navigate • ENTER Select • ESC Cancel

Model Selection

╔════════════════════════════════════════════════════════════════════════╗
║                       PERPLEXITY CLI • SELECT MODEL                ║
╚════════════════════════════════════════════════════════════════════════╝

● Sonar Pro (Best)       ── Recommended for complex queries
  ○ Sonar Medium           ── Faster responses
  ← Cancel

  ↑↓ Navigate • ENTER Select • ESC Cancel

Styled Messages

┌─ You ─────────────────────────────────────────────────────────
│ What is quantum computing?
└───────────────────────────────────────────────────────────────

┌─ Perplexity ────────────────────────────────────────────────
│ Quantum computing is a revolutionary field that uses
│ quantum mechanics to process information in ways
│ classical computers cannot...
└───────────────────────────────────────────────────────

📚 Sources
  [1] https://example.com/quantum-intro
  [2] https://example.com/qubits-explained

📁 File Locations

File/Folder	Linux/macOS	Windows	Purpose
.env	~/.perplexity/.env	%USERPROFILE%\.perplexity\.env	API key configuration
Conversations	~/.cache/perplexity/	%USERPROFILE%\.cache\perplexity\	Saved chat history
Script	~/.local/bin/perplexity	%USERPROFILE%\perplexity.py	CLI executable

💬 Tips & Tricks

• Custom Personas: Use --system to create different AI personalities

  • "You are a sarcastic comedian"
  • "You are a senior code reviewer"
  • "You explain things like I'm 5"

• Faster Responses: Use sonar-small-online for quick answers

• Interrupting: Press Ctrl+C to interrupt long responses

• Research: Use --search for complex topics requiring citations

• Documentation: Export chats to Markdown for documentation

🐛 Troubleshooting

API Key Not Found

Error: API key not found. Set PERPLEXITY_API_KEY or create ~/.perplexity/.env

Solution: Create an .env file or set the environment variable.

Module Not Found

ModuleNotFoundError: No module named 'openai'

Solution: Install dependencies with pip install openai python-dotenv

Colors Not Showing

Linux/macOS: Colors are automatically disabled when piping to a file or using --no-color.

Windows: If colors aren't showing:

• Use Windows Terminal or PowerShell 7+ (supports ANSI colors)
• For older Command Prompt, colors may not work - use perplexity --no-color
• Use PowerShell 5.1+: Install Windows Terminal for best experience

📄 License

MIT License - see LICENSE for details.

🤝 Contributing

Contributions are welcome! Feel free to:

• Open an issue for bugs or feature requests
• Submit a pull request with improvements
• Share your creative prompt ideas

🙏 Credits

• Built with Perplexity AI API
• Inspired by Ollama CLI
• ASCII art generated with figlet

---

Made with ♥ by Dodothereal