pplx-cli v1: a local-first research CLI

23 July, 2026

pplx-cli started as a direct way to use Perplexity from the terminal. Version 1 turns it into something broader: a local-first research tool that can search a body of evidence, turn it into an editable Markdown wiki, and still let me choose the model provider that fits the job.

The pplx-cli knowledge graph visualizes links in a Markdown research vault.

A pplx-cli knowledge graph: linked Markdown stays portable and inspectable rather than disappearing into a proprietary workspace.

A wiki that keeps the source material in charge

The biggest addition in v1 is perplexity wiki: an open research workspace built around ordinary files. I can point it at Markdown, text PDFs, and captured web pages; the source files stay where they are. The CLI creates a rebuildable .pplx/ index and a wiki/ directory of generated Markdown pages.

research/
├── papers/     # my original source material
├── wiki/       # generated, editable Markdown pages
└── .pplx/      # local index and captured web snapshots

The important boundary is deliberate: generated pages help with navigation, but they are not treated as evidence. Queries retrieve the original chunks and attach source locators. That makes it possible to follow an answer back to the file, page, or URL it came from—and makes “I don't have enough evidence” a valid result.

Here is the small workflow I reach for:

perplexity wiki init --dir ~/research
perplexity wiki sync --dir ~/research
perplexity wiki compile --dir ~/research
perplexity wiki query "What do my sources say about RAG evaluation?" --dir ~/research

sync is incremental and idempotent, while compile is explicit. That means a watcher can keep the index current without silently overwriting the wiki. Compilation updates only marked generated sections, preserving anything I put under Manual notes.

Retrieval that shows its work

v1 also improves the RAG layer underneath the wiki. Retrieval is source-centric now: every result keeps the metadata and chunk locator needed to inspect it later. Hybrid search combines vector search with full-text search using reciprocal-rank fusion, then reranks candidates.

The default embedding path stays local with BGE. When sqlite-vec is available, it supplies KNN search; when it is not, the CLI explicitly falls back to exact in-process similarity search rather than failing or pretending the index is working normally.

There is also a practical way to measure retrieval quality instead of merely trusting it:

perplexity rag eval --dir ~/research --dataset retrieval-eval.jsonl

The report includes Recall@k, MRR, nDCG, and the queries for which no relevant source was retrieved.

Provider choice without changing the workflow

The original Perplexity experience is still there, but it is no longer the only option. pplx-cli now supports Perplexity, NVIDIA NIM, and OpenRouter behind one chat interface. Setup selects a default provider, and individual requests can override it when needed:

perplexity setup
perplexity ask --provider nvidia \
  --model meta/llama-3.3-70b-instruct "Explain retrieval-augmented generation"
perplexity ask --provider openrouter \
  --model openrouter/free "Summarize the CAP theorem"

Local wiki answers and optional web research stay visibly separate. The --web path uses Perplexity for current research and prints its web citations separately from the local evidence, so the two kinds of claims do not blur together.

A few details that make v1 feel complete

perplexity ask --wiki ~/research "…" provides a quick wiki-backed answer without changing ordinary chat-history behavior.
perplexity wiki mcp exposes read-only tools for agents: search, source reading, page reading, and workspace status.
perplexity wiki lint checks generated pages for stale citations and broken wikilinks.
Note ordering is deterministic now, avoiding CI flakes when SQLite timestamps tie.

The full test suite for the release passed with 165 tests. For me, that is the point of this version: a research CLI should be useful in the happy path, but it should also be explicit about provenance, safe around my files, and predictable when it is automated.

To get started:

pip install pplx-cli
perplexity setup

The project is open source on GitHub. The full command surface is available through perplexity wiki --help.