pplx

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 <(pplx completion bash)

Permanent installation:

Linux:

pplx completion bash | sudo tee /etc/bash_completion.d/pplx

macOS (with Homebrew):

pplx completion bash > $(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 <(pplx completion zsh)

Permanent installation:

# Create completions directory if it doesn't exist
mkdir -p ~/.zsh/completions

# Generate completion script
pplx completion zsh > ~/.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 <TAB>
# Shows: chat, completion, config, help, mcp-stdio, query, version

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

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

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

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

# Complete multiple values for array flags
pplx query --search-domains <TAB>
# 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 | |--------|-------|------|------