Pplx

pplx

[](https://goreportcard.com/report/github.com/sgaunet/pplx)

[](https://github.com/sgaunet/pplx/actions/workflows/snapshot.yml) [](https://github.com/sgaunet/pplx/actions/workflows/release.yml) [](https://godoc.org/github.com/sgaunet/pplx) [](https://github.com/sgaunet/pplx/blob/main/LICENSE)

It's an unofficial CLI program to query/chat with the perplexity API.

Requirements

• Go 1.24.0 or later is required to build from source

If you're installing pre-built binaries, no Go installation is needed.

Installation

Option 1

• Download the latest release from the releases page.
• Install the binary in /usr/local/bin or any other directory in your PATH.

Option 2: With brew

brew tap sgaunet/homebrew-tools
brew install sgaunet/tools/pplx

Usage

Program to interact with the Perplexity API.

        You can use it to chat with the AI or to query it.

Usage:
  pplx [command]

Available Commands:
  chat        chat subcommand is an interactive chat with the Perplexity API
  help        Help about any command
  query       
  version     print version of pplx

Flags:
  -h, --help   help for pplx

Use "pplx [command] --help" for more information about a command.

Shell Completion

pplx supports shell completion for Bash, Zsh, Fish, and PowerShell, providing intelligent auto-completion for commands, flags, and values.

Features

• Command completion: Auto-complete available commands and subcommands
• Flag completion: Auto-complete flag names with descriptions
• Dynamic value completion: Intelligent completion for:
• Model names (e.g., sonar, sonar-pro, sonar-deep-research)
• Search modes (web, academic)
• Recency filters (hour, day, week, month, year)
• Context sizes (low, medium, high)
• Reasoning efforts (low, medium, high)
• Image formats (jpg, png, gif, etc.)
• Common domains for search filtering

Quick Installation

The easiest way to set up completions is using the automatic installer:

# Auto-detect your shell and install
pplx completion install

# Or specify a shell explicitly
pplx completion install bash
pplx completion install zsh
pplx completion install fish
pplx completion install powershell

To uninstall:

pplx completion install --uninstall

Manual Installation

If you prefer manual installation, you can generate completion scripts for your shell:

Bash

For current session only:

source  $(brew --prefix)/etc/bash_completion.d/pplx

Zsh

Prerequisites: If shell completion is not already enabled, add this to your ~/.zshrc:

autoload -U compinit; compinit

For current session only:

source  ~/.zsh/completions/_pplx

# Add to your ~/.zshrc (if not already present)
fpath=(~/.zsh/completions $fpath)
autoload -U compinit; compinit

Fish

For current session only:

pplx completion fish | source

Permanent installation:

pplx completion fish > ~/.config/fish/completions/pplx.fish

PowerShell

For current session only:

pplx completion powershell | Out-String | Invoke-Expression

Permanent installation:

# Generate completion script
pplx completion powershell > pplx-completion.ps1

# Add to your PowerShell profile
# Find your profile location with: $PROFILE
# Then add this line to your profile:
. /path/to/pplx-completion.ps1

Using Completions

Once installed, you can use tab completion for commands and flags:

# Complete command names
pplx 
# Shows: chat, completion, config, help, mcp-stdio, query, version

# Complete flag names
pplx query --m
# Completes to: --model

# Complete model names
pplx query --model 
# Shows: sonar, sonar-pro, sonar-reasoning, sonar-deep-research, etc.

# Complete search modes
pplx query --search-mode 
# Shows: web, academic

# Complete recency values
pplx query --search-recency 
# Shows: hour, day, week, month, year

# Complete multiple values for array flags
pplx query --search-domains 
# Shows: github.com, stackoverflow.com, medium.com, etc.

Troubleshooting

Completions not working after installation:

1. Restart your shell or source your shell configuration file:

• Bash: source ~/.bashrc or source ~/.bash_profile
• Zsh: source ~/.zshrc
• Fish: source ~/.config/fish/config.fish
• PowerShell: . $PROFILE

Zsh completions not loading:

• Ensure compinit is called in your ~/.zshrc
• Verify the completion file is in your fpath by running echo $fpath
• Try running compinit manually to reload completions

Permission errors during installation:

• Use the automatic installer which handles permissions correctly
• Or use sudo when writing to system directories

Advanced Usage

Save to a custom file:

pplx completion bash -o ~/my-completions/pplx.bash

Generate for a specific shell without installing:

pplx completion zsh > completions.zsh

View all completion subcommands:

pplx completion --help

Chat

Chat with the Perplexity API.

pplx chat

Query

Query the Perplexity API.

pplx query -p "what are the best citations of Jean Marc Jancovici ?" -s "you're a politician"

The above command will return in console a result that looks like:

Query Examples

Basic Queries

# Simple query
pplx query -p "What is the capital of France?"

# Query with system prompt
pplx query -p "Explain quantum computing" -s "You are a physics professor"

# Query with custom model
pplx query -p "Latest AI news" --model "llama-3.1-sonar-large-128k-online"

Advanced Search Options

# Search only from specific domains (using short flag)
pplx query -p "climate change research" -d nature.com,science.org

# Get recent information only (last week) - using short flag
pplx query -p "stock market updates" -r week

# Location-based query
pplx query -p "weather forecast" --location-lat 48.8566 --location-lon 2.3522 --location-country FR

Response Enhancement

# Include images in the response (using short flag)
pplx query -p "Famous landmarks in Paris" -i

# Get related questions (using short flag)
pplx query -p "How to learn programming" -q

# Filter images by format and domain
pplx query -p "Nature photography" -i --image-formats jpg,png --image-domains unsplash.com,pexels.com

Generation Parameters

# Control response length (using short flag)
pplx query -p "Summarize War and Peace" -T 500

# Fine-tune creativity and randomness (using short flags)
pplx query -p "Write a haiku about coding" -t 0.8 --top-p 0.95

# Adjust frequency and presence penalties
pplx query -p "Explain machine learning concepts" --frequency-penalty 0.5 --presence-penalty 0.3

Combined Examples

# Technical research with specific sources and recent data (using short flags)
pplx query -p "Latest developments in quantum computing" \
  -d arxiv.org,nature.com \
  -r month \
  -q \
  -T 1000

# Local business search with images (using short flags)
pplx query -p "Best restaurants near me" \
  --location-lat 40.7128 \
  --location-lon -74.0060 \
  --location-country US \
  -i \
  -r week

# Creative writing with custom parameters (using short flags)
pplx query -p "Write a short story about AI" \
  -s "You are a creative science fiction writer" \
  -t 0.9 \
  -k 50 \
  -T 2000

Available Options

Common Options (for both chat and query)

| Option | Short | Type | Description | |--------|-------|------|-------------| | --model | -m | string | AI model to use | | --frequency-penalty | | float64 | Penalize frequent tokens (0.0-2.0) | | --max-tokens | -T | int | Maximum tokens in response | | --presence-penalty | | float64 | Penalize already present tokens (0.0-2.0) | | --temperature | -t | float64 | Response randomness (0.0-2.0) | | --top-k | -k | int | Consider only top K tokens | | --top-p | | float64 | Nucleus sampling threshold | | --timeout | | duration | HTTP request timeout | | --search-domains | -d | []string | Filter search to specific domains | | --search-recency | -r | string | Filter by time: day, week, month, year | | --search-mode | -a | string | Search mode: web (default) or academic | | --search-context-size | -c | string | Search context size: low, medium, or high | | --location-lat | | float64 | User location latitude | | --location-lon | | float64 | User location longitude | | --location-country | | string | User location country code | | --return-images | -i | bool | Include images in response (automatically disables --search-recency) | | --return-related | -q | bool | Include related questions | | --stream | -S | bool | Enable streaming responses | | --image-domains | | []string | Filter images by domains | | --image-formats | | []string | Filter images by formats |

Query-specific Options

| Option | Short | Type | Description | |--------|-------|------|-------------| | --user-prompt | -p | string | User question/prompt (required) | | --sys-prompt | -s | string | System prompt to set AI behavior |

Configuration Files

pplx supports YAML configuration files to manage default settings and create reusable profiles for different use cases. This eliminates the need to specify the same flags repeatedly.

Quick Start

The easiest way to get started is with the interactive configuration wizard:

# Set your API key
export PERPLEXITY_API_KEY="your-api-key-here"

# Launch interactive wizard (recommended for first-time setup)
pplx config init --interactive

# Run your first query
pplx query -p "What are the latest developments in AI?"

The interactive wizard guides you through all configuration options with helpful prompts and suggestions.

Template-Based Quick Start

Alternatively, start quickly with pre-configured templates optimized for specific use cases:

# For academic research with scholarly sources
pplx config init --template research

# For creative writing and brainstorming
pplx config init --template creative

# For current news and events
pplx config init --template news

# View all available options with detailed documentation
pplx config init --template full-example

Each template comes with pre-tuned settings for temperature, search modes, domain filtering, and more. You can also browse all templates in the [examples/config/](examples/config/) directory.

Manual Configuration

For advanced users or automation:

# Create a minimal configuration file
pplx config init

# View current configuration
pplx config show

# Validate configuration
pplx config validate

# Edit configuration in your default editor
pplx config edit

For comprehensive configuration documentation, see [docs/configuration-guide.md](docs/configuration-guide.md).

Configuration File Locations

pplx searches for configuration files in the following order:

1. ~/.config/pplx/config.yaml - User config directory
2. ~/.config/pplx/pplx.yaml - Alternative user config
3. ~/.config/pplx/config.yml - YAML variant
4. ~/.config/pplx/pplx.yml - Alternative YAML variant

The first file found is used. Use pplx config path to see the active configuration file.

You can also specify a custom config file:

pplx query -p "your question" --config /path/to/config.yaml

Configuration Precedence

Settings are applied in the following order (later sources override earlier ones):

1. Configuration file defaults
2. Active profile settings (if using profiles)
3. Environment variables (e.g., PERPLEXITY_API_KEY)
4. Command-line flags (highest priority)

This allows you to set sensible defaults in your config file while still overriding them on the command line when needed.

Configuration Structure

A configuration file has four main sections:

# Default values for all queries
defaults:
  model: sonar
  temperature: 0.2
  max_tokens: 4000

# Search preferences
search:
  mode: web                    # web or academic
  recency: week               # hour, day, week, month, year
  context_size: medium        # low, medium, high
  domains:                    # Optional domain filtering
    - nature.com
    - science.org

# Output preferences
output:
  stream: false
  return_images: false
  return_related: false
  json: false

# API configuration
api:
  timeout: 30s

Environment Variable Interpolation

Configuration values can reference environment variables using ${VAR_NAME} syntax:

api:
  key: ${PPLX_API_KEY}
  timeout: ${PPLX_TIMEOUT:-30s}  # With default fallback

Working with Profiles

Profiles allow you to maintain different configurations for various use cases (research, creative writing, news, etc.).

Creating Profiles

# Create a new profile
pplx config profile create research "Academic research with verified sources"

# List all profiles
pplx config profile list

# Switch active profile
pplx config profile switch research

# Delete a profile
pplx config profile delete creative

Using Profiles in Config Files

# Active profile to use by default
active_profile: research

# Define multiple profiles
profiles:
  research:
    name: research
    description: Academic research with verified sources
    defaults:
      model: llama-3.1-sonar-large-128k-online
      temperature: 0.1
      max_tokens: 2000
    search:
      mode: academic
      context_size: high
      recency: month
      domains:
        - arxiv.org
        - nature.com
        - science.org
    output:
      return_related: true

  creative:
    name: creative
    description: Creative writing and brainstorming
    defaults:
      model: sonar
      temperature: 0.9
      max_tokens: 4000
      frequency_penalty: 0.5
    output:
      stream: true
      return_images: true

  news:
    name: news
    description: Current news and events
    defaults:
      model: sonar
      temperature: 0.2
    search:
      recency: day
      context_size: high
      domains:
        - reuters.com
        - bbc.com
        - apnews.com
    output:
      return_related: true
      return_images: true

Using Profiles from CLI

# Use a specific profile for a query
pplx config profile switch research
pplx query -p "Latest quantum computing research"

# Or override the active profile temporarily
pplx query -p "Write a creative story" --config creative.yaml

Configuration Management Commands

Initialize Configuration

# Create a new config file with defaults
pplx config init

# Create in a specific location
pplx config init --output ~/.config/pplx/config.yaml

# Force overwrite existing config
pplx config init --force

View Configuration

# Show current configuration
pplx config show

# Show specific profile
pplx config show --profile research

# Show configuration from specific file
pplx config show --config /path/to/config.yaml

Validate Configuration

# Validate current configuration
pplx config validate

# Validate specific file
pplx config validate --config /path/to/config.yaml

Edit Configuration

# Open config in default editor
pplx config edit

# Edit specific config file
pplx config edit --config /path/to/config.yaml

Example Use Cases

Research Workflow

Create a research profile for academic queries:

profiles:
  research:
    defaults:
      model: llama-3.1-sonar-large-128k-online
      temperature: 0.1
      max_tokens: 2000
    search:
      mode: academic
      context_size: high
      recency: month
      domains:
        - arxiv.org
        - nature.com
        - science.org
        - ieee.org
    output:
      return_related: true

Use it:

pplx config profile switch research
pplx query -p "Latest breakthroughs in quantum computing"

##

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sgaunet
• Source: sgaunet/pplx
• License: MIT

Install and usage instructions live in the source repository linked above.