Getting Started

Installation

Clone the repository and build the binary using Bun:

git clone https://github.com/perplx-ai/perplx.git
cd perplx/tool
pnpm install
bun build src/cli.ts --target node --compile --outfile ~/.local/bin/perplx

This compiles the agent into a standalone binary at ~/.local/bin/perplx. Make sure ~/.local/bin is in your PATH.

For development, you can run directly without compiling:

cd perplx/tool
pnpm dev

Authentication

perplx uses the Perplexity API. On first launch, you'll be guided through authentication via OAuth — you'll need a Perplexity API key.

$ perplx
# On first run, you'll be prompted:
#   Go to https://console.perplexity.ai
#   Navigate to the API Keys tab and generate a new key.
#   Paste your Perplexity API key: pplx-xxxxxxxx...

Your credentials are stored locally at ~/.perplx/agent/auth.json.

First Run

Navigate to any project directory and launch the agent:

cd ~/my-project
perplx

You'll enter interactive mode where you can ask the agent to read, write, refactor, and debug code. The agent has access to tools for file operations, shell commands, and web search.

Interactive Mode

The default mode. Launch perplx with no flags to enter a persistent session where you can have a back-and-forth conversation with the agent.

$ perplx
> add error handling to the database module
> now write tests for it

Use Ctrl+P to cycle between available models during a session.

Print Mode

For scripting and pipelines. Pass --print (or -p) to run non-interactively — the agent processes your prompt and exits.

perplx -p "explain this function" @src/utils.ts

You can also pipe stdin into perplx:

cat error.log | perplx "what went wrong?"

File Input

Prefix file paths with @ to attach them as context to your prompt. This works in both interactive and print mode.

perplx @src/auth.ts @src/middleware.ts "refactor these to use a shared session"

Image files are supported too — the agent can analyze screenshots, diagrams, and other visuals.

Sessions

Every conversation is automatically saved. You can continue your most recent session or browse and resume any previous one.

# Continue the last session
perplx --continue

# Browse and select a session to resume
perplx --resume

Sessions are stored locally in ~/.perplx/agent/sessions/.

You can also share sessions publicly via share.perplx.net. Shared sessions are rendered with full markdown and syntax highlighting.

Available Models

perplx ships with three model tiers, all served through the Perplexity Agent API:

The default model is smart. Use Ctrl+P in interactive mode to switch between models on the fly.

CLI Flags

Configuration

All configuration lives under ~/.perplx/: