Skip to content

Getting started

From a fresh checkout to a first local archive: install the two commands, create the user-level config, choose a cookie channel, and walk through a first export.

Requirements

  • Python ≥ 3.11
  • uv — used to install the tools and run the test suite
  • A desktop browser logged into Perplexity — the tools reuse its session cookies; no token is ever stored in the config

Cookie decryption uses browser_cookie3. Auto-detect covers Edge, Chrome, Firefox and Safari; Brave, Chromium, Opera and Vivaldi work via --cookies-from.

1. Install

From the repo root:

uv tool install .            # or development mode: uv tool install --editable .

This installs two commands: pplx-export (archiving) and pplx-ask (interactive queries). Verify:

pplx-export --version
pplx-export --help           # overview with examples; each subcommand has its own --help
pplx-ask --help

uvx --from . pplx-export runs a one-off command without installing.

2. Create the user-level config

The account registry (display name / email / user_id) and the BOT space are personal data and are not committed to the repo; they live in an external TOML file. Template: config.example.toml at the repo root.

mkdir -p ~/.config/pplx-export
cp config.example.toml ~/.config/pplx-export/config.toml
chmod 600 ~/.config/pplx-export/config.toml   # personal data — keep it owner-only
# edit and fill in your real account values
  1. Create the config directory.
  2. Copy the template to the default path.
  3. chmod 600 — the file holds personal data; keep it owner-only.
  4. Fill in [accounts.<name>] — the key is the account username (as it appears in thread URLs / the library); set display_name, email, user_id, and pick a default_account.
  5. Fill in [bot_space] — where threads created by pplx-ask are collected after completion (a real space can be created with pplx-ask space-create).

The full field reference lives in Configuration.

Load priority (highest first):

# Source
1 --config PATH
2 PPLX_EXPORT_CONFIG environment variable
3 ~/.config/pplx-export/config.toml (default)

When the config is missing

Commands without --account run in a degraded mode — the email ownership check is skipped with a warning (offline commands are unaffected); an explicit --account raises an error pointing at config.example.toml. When --account is omitted, default_account from the config is used.

Credentials come from your local browser's logged-in Perplexity session cookies, read via browser_cookie3 — including multi-account token enumeration and automatic switching. Four channels:

Channel How Notes
Auto-detect (default) no flag fresh 12 h cache first, then browser stores in the order edge→chrome→firefox→safari
Named browser --cookies-from <browser> edge / chrome / firefox / safari / brave …
Cookie file --cookies /path/to/cookies.txt Netscape cookie file or exported JSON
WebBridge --transport webbridge page-context fetch — the fallback channel, only used when explicitly requested 
pplx-export export <thread_url>                                 # default: auto-detect browser store
pplx-export export <thread_url> --cookies-from edge             # import from a specific browser
pplx-export export <thread_url> --cookies /path/to/cookies.txt  # use a cookie file
pplx-export export <thread_url> --transport webbridge           # WebBridge page context (explicit fallback)

After cookies are obtained, the tool calls /api/auth/session and prints the current account email so you can confirm the right account is in use — watch out if --account disagrees with the cookie account. The transport/credential design is covered in Ask & accounts.

4. First run

pplx-export index --account alice     # fetch the library index
pplx-export export <thread_url>       # export a single thread
pplx-export batch --account alice     # batch (incremental early-stop by default; --full for a full sweep)
pplx-export re-render --dry-run       # offline re-render, zero network
  1. index fetches the account's library index — the entry point that batch and the other account-wide commands build on.
  2. export archives one thread end to end: raw API responses are persisted first (raw_*.json), then rendered to Markdown.
  3. batch sweeps the whole library. It stops early once everything remaining is already archived (incremental early-stop), writes resumable checkpoints, and accepts --full for a full sweep. Details: Incremental sync.
  4. re-render --dry-run proves the offline path: it regenerates conversation.md
  5. turns/ from local raw files with zero network. Drop --dry-run to write the results. See Offline operations.

Once that works, pplx-ask ask "<prompt>" runs a streaming query and archives the resulting thread automatically — see pplx-ask.

5. Where archives land

Archives are written to ./web_archive/ by default (override with --out): one directory per thread.

Path Content
conversation.md, turns/ rendered conversation
thread.json thread metadata + interruptions registry
sources.md / sources.json citations
report.md deep-research / council / study report
assets/ downloaded assets (computer mode)
raw_*.json raw API responses — persisted first, so re-rendering is always possible offline

The full directory contract: Archive layout.

Next steps