Fast, non-interactive, agent-first CLI wrapper for the Perplexity API.
- Fast: Minimal overhead, direct API calls
- Non-interactive: No prompts, perfect for automation and agents
- Agent-friendly: Structured output, semantic exit codes, machine-readable help
- Multiple output formats:
text,json,plain - Supercli plugin: Works as a plugin for supercli ecosystems
npm install -g pplxOr use locally:
npm install
npm linkSet your Perplexity API key via environment variable:
export PERPLEXITY_API_KEY=pplx-xxxxxxxxxxxxxxxxxxxxxxxxOr pass it directly as an argument:
pplx chat "Question" --api-key pplx-xxxGet your API key from: https://www.perplexity.ai/settings/api
Priority: --api-key argument overrides PERPLEXITY_API_KEY environment variable.
Send a chat completion request:
# Basic usage (API key from env)
pplx chat "What is quantum computing?"
# API key from argument
pplx chat "What is quantum computing?" --api-key pplx-xxx
# With specific model
pplx chat "Explain Rust ownership" --model sonar-pro
# JSON output (agent-friendly)
pplx chat "Latest AI news" --json
# With citations
pplx chat "Climate change research 2025" --citations --json
# With system prompt
pplx chat "Explain recursion" --system "You are a helpful programming tutor"
# Plain output (for piping)
pplx chat "What is Docker?" --plainSimplified chat for questions:
pplx ask "What is the capital of France?"
pplx ask "How does async/await work?" --json
pplx ask "Latest TypeScript features" --citationsList available models:
# Human-readable
pplx models
# JSON output
pplx models --json
# Plain list (model IDs only)
pplx models --plain# Human-readable help
pplx --help
pplx chat --help
# Machine-readable schema (agent-friendly)
pplx help-jsonStructured, human-readable output with sections:
--- Response ---
Model: sonar
ID: cmpl-xxx
Tokens: 245 (prompt: 50, completion: 195)
--- Content ---
Quantum computing is a type of computation...
--- Citations ---
[1] https://example.com/article1
[2] https://example.com/article2
Full structured output with stable schema:
{
"version": "1.0",
"id": "cmpl-xxx",
"model": "sonar",
"created": 1234567890,
"usage": {
"total_tokens": 245,
"prompt_tokens": 50,
"completion_tokens": 195
},
"citations": ["https://..."],
"choice": {
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": "Quantum computing is..."
}
}
}Minimal output, perfect for piping:
Quantum computing is a type of computation...
--- Citations ---
[1] https://example.com/article1
Semantic exit codes for programmatic decision-making:
| Code | Type | Description | Retry? |
|---|---|---|---|
| 0 | success |
Request completed successfully | No |
| 85 | invalid_argument |
Missing/invalid API key, bad arguments | No |
| 87 | authentication_required |
Invalid API key | No |
| 100 | network_error |
Network request failed | Yes |
| 105 | request_timeout |
Request timed out | Yes |
| 106 | rate_limited |
API rate limit exceeded | Yes (after delay) |
| 110 | internal_error |
Internal server error | Yes |
pplx chat "Question" --json
exit_code=$?
case $exit_code in
0)
# Success - parse and use result
;;
85|87)
# User error - don't retry, fix config
;;
100|105|106)
# Transient error - retry with backoff
;;
110)
# Server error - report or retry
;;
esac| Variable | Description | Required |
|---|---|---|
PERPLEXITY_API_KEY |
Perplexity API key | Yes |
NO_COLOR |
Disable color output | No |
| Model | Description |
|---|---|
sonar |
Fast online search |
sonar-pro |
Advanced online search |
sonar-deep-research |
Deep research with citations |
sonar-reasoning |
Reasoning with search |
sonar-reasoning-pro |
Advanced reasoning |
# Get answer with citations for verification
pplx chat "What caused the 2008 financial crisis?" --citations --json | \
jq '{content: .choice.message.content, citations: .citations}'
# List models and select one
pplx models --json | jq -r '.data[] | select(.name == "Sonar Pro") | .id'
# Pipe to another command
pplx ask "Explain monads" --plain | grep -A5 "category theory"#!/bin/bash
QUESTION="What is the time complexity of quicksort?"
response=$(pplx chat "$QUESTION" --json)
exit_code=$?
if [ $exit_code -eq 0 ]; then
echo "$response" | jq -r '.choice.message.content'
elif [ $exit_code -eq 106 ]; then
echo "Rate limited, waiting..."
sleep 60
pplx chat "$QUESTION" --json
else
echo "Error: $exit_code" >&2
exit $exit_code
fiUse as a supercli plugin:
# Via supercli
supercli run pplx chat "Question" --json
# Direct plugin usage
node src/supercli.jsThis CLI follows agent-friendly design principles:
- Machine-friendly escape hatches:
--no-interactive,--json,--plain - Output as API contracts: Stable, versioned JSON schema
- Semantic exit codes: Actionable error signals
- Structured output: Separate stdout (data) from stderr (logs)
- Real-time feedback: Progress on stderr for long operations
See AGENTS_FRIENDLY_TOOLS.md for more details.
This project is licensed under the MIT License.
Copyright (c) 2026 Javier Leandro Arancibia
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
See the LICENSE file for the full license text.