pplx-npx-search 0.1.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to pplx-cli will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.2] - 2026-05-21
+
+### Added
+- **Configurable stream timeout.** `search`, `reason`, and `research` now accept `--timeout-ms <duration>`, with support for raw milliseconds plus `s` and `m` suffixes.
+
+### Changed
+- `pplx research` now defaults to a 10-minute stream timeout so Deep Research can finish instead of hitting the old 2-minute ceiling.
+- `pplx --version` now reads from `package.json`, keeping CLI output aligned with npm releases.
+
+## [0.2.1] - 2026-05-18
+
+First public release worth telling people about. (v0.2.0 was unpublished before this release; do not use it.)
+
+### Added
+- **Multi-browser cookie auto-detection.** `pplx auth --browser auto` now tries Chrome, Chrome Beta, Comet, and Dia in turn and uses the first browser that yields an authenticated session. Force a specific store with `pplx auth --browser <chrome|chrome-beta|comet|dia>`.
+- **Session-level auth validation.** `pplx auth` and `pplx auth --test` no longer accept "I extracted some bytes" as success. They verify the extracted cookies resolve to a signed-in Perplexity session by hitting `/api/auth/session` and checking for a user identity.
+- **`--no-playwright` flag** on `search`, `reason`, and `research` to force HTTP transport when the config file enables Playwright by default.
+- **`--allow-anonymous` flag** to permit anonymous Perplexity responses when cookies are expired (instead of hard-failing).
+- **Pre-search auth check** with actionable error message. If stored cookies are stale, the CLI now prints `Run: pplx auth --browser auto` instead of silently degrading.
+- **Per-browser diagnostics** in the auth flow. When extraction fails, the CLI lists every browser it tried with cookie count and status (`valid`, `expired`, `no session`) so you can see exactly which store is broken.
+- **Defensive `.gitignore` entries** for `cookies.json` and local `.config/` directories.
+- **`test/session.test.js`** covering the `isAuthenticatedSession` helper.
+
+### Changed
+- Auth error UX is tighter: missing-session and expired-session cases now print distinct messages and exit codes, and never overwrite a working cookie file with a broken one.
+- Token preview line removed from auth success output. Session tokens are credentials and should not be echoed to stdout, even truncated.
+- `--playwright` is opt-in per invocation. Setting `"playwright": true` in the config file no longer makes `pplx auth` use Playwright by default.
+
+### Documentation
+- README restructured around a **Quick Start** that makes the login-first requirement explicit, plus a dedicated **Agent Usage** section for headless and CI use.
+- Added a **Security** callout: never commit `cookies.json`, never paste it into a chat.
+- Added a **Troubleshooting** table covering the common Keychain, browser store, and TLS fingerprinting failures.
+
+## [0.1.1] - 2026-02-04
+
+### Added
+- Codex auto-fallback (HTTP → Playwright → curl-impersonate)
+- Playwright as opt-in default transport
+- Automatic curl-impersonate download when needed
+- Acknowledgement of `helallao/perplexity-ai` upstream project
+
+## [0.1.0] - 2026-02-02
+
+### Added
+- Initial release: cookie-authenticated Perplexity CLI
+- `search`, `reason`, `research`, `labs`, `models` commands
+- Cookie extraction from Chrome on macOS and Linux
+- SSE streaming for real-time answers
+- Optional Playwright and Chrome CDP transports
+
+[0.2.2]: https://github.com/thatsrajan/pplx-cli/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/thatsrajan/pplx-cli/compare/v0.1.1...v0.2.1
+[0.1.1]: https://github.com/thatsrajan/pplx-cli/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/thatsrajan/pplx-cli/releases/tag/v0.1.0

package/README.md

@@ -1,91 +1,187 @@
 # pplx-cli
 
-CLI for Perplexity AI with cookie-based authentication. Designed for headless/agent-first usage — no browser required at runtime.
+[![npm version](https://img.shields.io/npm/v/pplx-npx-search.svg)](https://www.npmjs.com/package/pplx-npx-search)
+[![license](https://img.shields.io/npm/l/pplx-npx-search.svg)](./LICENSE)
+
+A cookie-authenticated CLI for **Perplexity AI**. Built for headless and agentic usage — no browser required at runtime, no API key, no per-call billing beyond your existing Perplexity Pro subscription.
+
+```bash
+npm install -g pplx-npx-search
+pplx auth --browser auto
+pplx auth --test
+pplx search "what shipped in Claude 4.7 this week" --json --raw
+```
+
+That's the whole loop. Cookies live at `~/.config/pplx/cookies.json`, never paste them by hand.
+
+---
+
+## Why this exists
+
+Perplexity has no public consumer-tier API. Power users who already pay for Pro want shell and agent access without paying again per-call for the API. pplx-cli reads the cookies from your already-signed-in browser and uses them headlessly, so:
+
+- **No API key.** Cookies come from your real session.
+- **No re-billing.** Calls count against your existing Pro quota.
+- **Agent-friendly.** `--json` and `--raw` flags are designed for piping into LLMs, agents, and scripts.
+- **TLS fingerprinting fallback.** When Cloudflare gets aggressive, the CLI auto-falls back to Playwright or curl-impersonate.
+
+This is a ground-up Node.js reimplementation inspired by the reverse-engineering work in [helallao/perplexity-ai](https://github.com/helallao/perplexity-ai) — see [Acknowledgements](#acknowledgements).
+
+---
 
 ## Prerequisites
 
-- Node.js 20+
-- Google Chrome (only for initial cookie extraction via `pplx auth`)
+- Node.js 20 or newer
+- A logged-in session in **Chrome, Chrome Beta, Comet, or Dia** (macOS) or **Google Chrome** (Linux)
+- Optional: Playwright Chromium (`npx playwright install chromium`) for the `--playwright` transport
+
+---
+
+## Quick Start
+
+### 1. Log into Perplexity in your browser
+
+Before anything else, open one of the supported browsers (Chrome, Chrome Beta, Comet, or Dia) and **make sure you are signed into perplexity.ai**. The CLI extracts cookies from your real session; if you are not logged in, there is nothing to extract.
+
+### 2. Install the CLI
 
-## Installation
+```bash
+npm install -g pplx-npx-search
+
+# or run once without installing
+npx pplx-npx-search search "what is quantum computing"
+```
+
+If you would rather build from source:
 
 ```bash
-git clone https://github.com/rajanrengasamy/pplx-cli.git
+git clone https://github.com/thatsrajan/pplx-cli.git
 cd pplx-cli
 npm install
 npm link
 ```
 
-## Authentication
-
-Extract cookies from Chrome (one-time setup):
+### 3. Extract cookies once
 
 ```bash
-pplx auth
-pplx auth --test    # verify cookies work
+pplx auth --browser auto
 ```
 
-Cookies are stored at `~/.config/pplx/cookies.json`.
+`--browser auto` tries every supported browser in turn and uses the first one that yields a valid signed-in session. Force a specific browser if you have multiple installed:
+
+```bash
+pplx auth --browser chrome
+pplx auth --browser chrome-beta
+pplx auth --browser comet
+pplx auth --browser dia
+```
 
-## Usage
+If the browser stores are locked down (corporate machine, weird Keychain ACL, etc.) you can fall back to Playwright:
 
 ```bash
-# Search (default: pro mode, headless HTTP)
-pplx search "what is quantum computing"
+pplx auth --playwright
+```
 
-# Reasoning mode
-pplx reason "explain the Riemann hypothesis"
+Cookies are written to `~/.config/pplx/cookies.json`.
 
-# Deep research
-pplx research "compare React vs Vue in 2026"
+> **Security:** never commit `cookies.json` to a repo or paste its contents into a chat. The file is a complete session credential. The CLI never asks you to type cookies by hand and never logs them to stdout.
 
-# Labs (free, no auth needed)
-pplx labs "hello world"
+### 4. Verify
 
-# List models
-pplx models
+```bash
+pplx auth --test
 ```
 
-### Options
+This must report `✓ Cookies are valid` before agents start calling the CLI. If it fails, repeat step 1 (you may be signed out) then step 3.
+
+### 5. Use it
 
 ```bash
-pplx search "query" --mode auto|pro|reasoning|deep-research
-pplx search "query" --model claude-3.5-sonnet
-pplx search "query" --json          # single JSON object output
-pplx search "query" --raw           # plain text, no colors/spinner
-pplx search "query" --chrome        # use Chrome CDP bridge instead of HTTP
-pplx search "query" --curl          # force curl-impersonate for TLS
-pplx search "query" --incognito     # don't save to Perplexity history
-pplx search "query" --citations-full  # show full source details
+pplx search "what is quantum computing"
+pplx reason "explain the Riemann hypothesis"
+pplx research "compare React vs Vue in 2026"
+pplx labs "hello world"          # free, no auth needed
+pplx models                       # list available models
 ```
 
-## Agent/Automation Usage
+---
+
+## Agent Usage
 
-pplx-cli is designed to work in automated pipelines and with AI agents:
+pplx-cli is designed to be the Perplexity transport for AI agents, CI jobs, and headless scripts.
 
 ```bash
-# Plain text output (no colors, no spinner)
+# Plain text output, no colors, no spinner
 pplx search "query" --raw
 
+# Single JSON object: { answer, sources, query, mode, model }
+pplx search "query" --json
+
 # Read query from stdin
 echo "what is 2+2" | pplx search -
 
-# JSON output (single object: {answer, sources, query, mode, model})
-pplx search "query" --json
-
-# Pipe-friendly (auto-detects non-TTY)
+# Pipe-friendly: auto-detects non-TTY
 pplx search "query" | head -1
 
-# Non-zero exit code when no answer is returned
+# Non-zero exit when no answer is returned
 pplx search "query" --json || echo "failed"
 ```
 
+Deep Research is slower than normal search. `pplx research` defaults to a 10-minute stream timeout; override it per run with `--timeout-ms 600000`, `--timeout-ms 120s`, or `--timeout-ms 10m`.
+
+Recommended agent invocation:
+
+```bash
+pplx search "research this topic" --json --raw --mode pro
+```
+
+`--json --raw` gives a clean, deterministic envelope with no chrome around it:
+
+```json
+{
+  "answer": "...",
+  "sources": [
+    {"title": "...", "url": "..."}
+  ],
+  "query": "...",
+  "mode": "pro",
+  "model": "..."
+}
+```
+
+---
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--mode auto\|pro\|reasoning\|deep-research` | Search mode |
+| `--model claude-3.5-sonnet` | Pin a specific model |
+| `--json` | Single JSON object output |
+| `--raw` | Plain text, no colors, no spinner |
+| `--chrome` | Use Chrome CDP bridge instead of HTTP |
+| `--playwright` | Use Playwright headless Chromium |
+| `--no-playwright` | Force HTTP transport even if config enables Playwright |
+| `--timeout-ms 120000\|120s\|10m` | Overall stream timeout |
+| `--curl` | Force curl-impersonate (auto-downloads if missing) |
+| `--allow-anonymous` | Allow anonymous Perplexity responses when cookies are expired |
+| `--incognito` | Do not save the query to Perplexity history |
+| `--citations-full` | Show full source metadata in the rendered answer |
+
+---
+
 ## Architecture
 
-- **Default mode:** Headless HTTP with stored cookies (no browser needed)
-- **Optional:** `--chrome` flag uses Chrome CDP bridge for TLS fingerprinting bypass
-- **SSE streaming:** Real-time answer streaming via Server-Sent Events
-- **Cookie auth:** One-time extraction from Chrome, then fully headless
+| Layer | Detail |
+|---|---|
+| **Default transport** | Headless HTTP with stored cookies. No browser launched at runtime. |
+| **Optional transports** | `--chrome` Chrome CDP bridge, `--playwright` Playwright headless Chromium, `--curl` curl-impersonate for TLS fingerprinting. |
+| **Auto fallback** | HTTP → Playwright → curl-impersonate when TLS is blocked. |
+| **Streaming** | Real-time answer streaming via Server-Sent Events. |
+| **Auth** | One-time cookie extraction from Chrome / Chrome Beta / Comet / Dia (macOS Keychain) or `~/.config/google-chrome` (Linux). After that, fully headless. |
+| **Session validation** | `pplx auth --test` and `pplx auth --browser auto` both verify that the extracted cookies resolve to an authenticated session (not just "I extracted some bytes"). |
+
+---
 
 ## Configuration
 
@@ -95,15 +191,39 @@ Optional config file at `~/.config/pplx/config.json`:
 {
   "mode": "pro",
   "model": "claude-3.5-sonnet",
-  "lang": "en-US"
+  "lang": "en-US",
+  "playwright": true,
+  "playwrightHeadless": false
 }
 ```
 
+Set `"playwright": true` to make Playwright the default transport.
+
+Environment overrides:
+
+```bash
+PPLX_CURL_IMPERSONATE=/path/to/curl-impersonate-chrome
+```
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `Cookies are invalid or expired` | Open Perplexity in your browser, confirm you are signed in, then re-run `pplx auth --browser auto`. |
+| `Keychain access denied for "Chrome Safe Storage"` | macOS Keychain is prompting for permission. Run the exact `security find-generic-password` command the error suggests and click "Always Allow". |
+| `Chrome cookie DB not found at ...` | The selected browser is not installed at the default location, or the profile name is wrong. Pass `--browser <name>` or `--profile <name>`. |
+| Search hangs or times out | TLS fingerprinting may be in play. Try `pplx search "..." --playwright` or `--curl`. |
+| `npm install -g` succeeds but `pplx` not found | Your global `npm bin` directory is not on PATH. Find it with `npm bin -g` and add it. |
+
+---
+
 ## Acknowledgements
 
 This project was inspired by and built upon the reverse-engineering work in [helallao/perplexity-ai](https://github.com/helallao/perplexity-ai) — a Python library for the Perplexity AI API. The authentication flow, SSE protocol handling, and API structure were all derived from studying that project. Big thanks to [@helallao](https://github.com/helallao) for figuring out the hard parts.
 
-pplx-cli is a ground-up Node.js reimplementation for CLI/agentic use cases, but it wouldn't exist without that foundational work.
+pplx-cli is a ground-up Node.js reimplementation for CLI and agentic use cases, but it would not exist without that foundational work.
 
 ## License
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "pplx-npx-search",
-  "version": "0.1.0",
-  "description": "CLI for Perplexity AI with cookie-based auth",
+  "version": "0.2.2",
+  "description": "CLI for Perplexity AI with cookie-based auth. Headless, agent-friendly, no API key required.",
   "type": "module",
   "bin": {
-    "pplx": "./bin/pplx.js"
+    "pplx": "bin/pplx.js"
   },
   "scripts": {
     "start": "node bin/pplx.js",
@@ -20,12 +20,17 @@
   "author": "Rajan Rengasamy",
   "repository": {
     "type": "git",
-    "url": "https://github.com/rajanrengasamy/pplx-cli"
+    "url": "git+https://github.com/thatsrajan/pplx-cli.git"
   },
+  "bugs": {
+    "url": "https://github.com/thatsrajan/pplx-cli/issues"
+  },
+  "homepage": "https://github.com/thatsrajan/pplx-cli#readme",
   "files": [
     "bin",
     "src",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -37,6 +42,7 @@
     "commander": "^12.0.0",
     "eventsource-parser": "^3.0.0",
     "ora": "^8.0.0",
+    "playwright": "^1.58.1",
     "ws": "^8.16.0"
   }
 }

package/src/cli.js

@@ -1,7 +1,9 @@
+import { readFileSync } from 'node:fs';
 import { program } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
-import { extractFromChrome, loadCookies, saveCookies, cookieHeader } from './cookies.js';
+import { extractFromChrome, loadCookies, saveCookies, SUPPORTED_BROWSERS } from './cookies.js';
+import { extractFromPlaywright } from './playwright-auth.js';
 import { initSession, testAuth } from './session.js';
 import { search } from './search.js';
 import { LabsClient } from './labs.js';
@@ -9,6 +11,9 @@ import { formatSources } from './format.js';
 import { LABS_MODELS, MODEL_MAP } from './constants.js';
 import { setUseCurl } from './http.js';
 import { loadConfig } from './config.js';
+import { resolveTimeoutMs } from './timeout.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 
 // --- Output state ---
 let rawMode = false;
@@ -25,6 +30,15 @@ function makeSpinner(text) {
   return ora(text);
 }
 
+function finishSuccess(spinner, message) {
+  if (isQuiet()) {
+    spinner.stop();
+    console.log(chalk.green(`✓ ${message}`));
+    return;
+  }
+  spinner.succeed(message);
+}
+
 // --- Stdin helper ---
 function readStdin() {
   return new Promise((resolve, reject) => {
@@ -50,11 +64,31 @@ async function resolveQuery(queryArg) {
   process.exit(1);
 }
 
+async function extractAndValidateBrowser(browser, profile) {
+  const cookies = extractFromChrome(profile, browser);
+  const count = Object.keys(cookies).length;
+  const hasSession = Boolean(cookies['next-auth.session-token'] || cookies['__Secure-next-auth.session-token']);
+  if (!hasSession) {
+    return { browser, profile, cookies, count, hasSession, ok: false };
+  }
+
+  const session = await initSession(cookies);
+  return {
+    browser,
+    profile,
+    cookies: session.cookies,
+    count: Object.keys(session.cookies).length,
+    hasSession,
+    ok: session.ok,
+    status: session.status,
+  };
+}
+
 // --- Program setup ---
 program
   .name('pplx')
   .description('CLI for Perplexity AI')
-  .version('0.1.0');
+  .version(pkg.version);
 
 program.option('--verbose', 'Enable verbose logging');
 program.option('--proxy <url>', 'Set proxy URL (sets HTTPS_PROXY env var)');
@@ -76,10 +110,17 @@ program.hook('preAction', (thisCmd) => {
 // Auth command
 program
   .command('auth')
-  .description('Extract and manage cookies from Chrome')
+  .description('Extract and manage cookies from supported browsers')
   .option('--test', 'Test if stored cookies are valid')
   .option('--profile <name>', 'Chrome profile', 'Default')
+  .option('--browser <name>', `Browser store: auto, ${SUPPORTED_BROWSERS.join(', ')}`, 'auto')
+  .option('--playwright', 'Use Playwright to login and extract cookies')
+  .option('--headless', 'Run Playwright in headless mode (not recommended for login)')
   .action(async (opts) => {
+    const cfg = loadConfig();
+    const usePlaywright = opts.playwright === true;
+    const playwrightHeadless = opts.headless ?? cfg.playwrightHeadless ?? false;
+
     if (opts.test) {
       const cookies = loadCookies();
       if (!cookies) {
@@ -91,6 +132,9 @@ program
         const ok = await testAuth(cookies);
         spinner.stop();
         console.log(ok ? chalk.green('✓ Cookies are valid') : chalk.red('✗ Cookies are invalid or expired'));
+        if (!ok) {
+          console.log(chalk.dim('  Run: pplx auth --browser auto'));
+        }
         process.exit(ok ? 0 : 1);
       } catch (e) {
         spinner.stop();
@@ -100,9 +144,76 @@ program
       return;
     }
 
+    if (usePlaywright) {
+      const spinner = makeSpinner('Launching Playwright for login...').start();
+      try {
+        spinner.stop();
+        const cookies = await extractFromPlaywright({ headless: playwrightHeadless });
+        const count = Object.keys(cookies).length;
+        const hasSession = cookies['next-auth.session-token'] || cookies['__Secure-next-auth.session-token'];
+
+        if (!hasSession) {
+          console.log(chalk.yellow(`⚠ Found ${count} cookies but no session token.`));
+          console.log('  Make sure you are logged into perplexity.ai in Playwright.');
+          if (count > 0) {
+            saveCookies(cookies);
+            console.log(chalk.dim('  Saved cookies anyway.'));
+          }
+          return;
+        }
+
+        const { cookies: refreshed, ok } = await initSession(cookies);
+        if (!ok) {
+          console.log(chalk.red('✗ Login cookies were extracted but are not authenticated.'));
+          console.log(chalk.dim('  Try again after logging into Perplexity in the Playwright browser.'));
+          process.exit(1);
+        }
+        saveCookies(refreshed);
+        console.log(chalk.green(`✓ Extracted ${Object.keys(refreshed).length} cookies and saved to ~/.config/pplx/cookies.json`));
+        return;
+      } catch (e) {
+        spinner.stop();
+        console.error(chalk.red('Failed to extract cookies via Playwright'));
+        console.error(chalk.red(e.message));
+        process.exit(1);
+      }
+    }
+
     const spinner = makeSpinner('Extracting cookies from Chrome...').start();
     try {
-      const cookies = extractFromChrome(opts.profile);
+      const attempts = [];
+      let result = null;
+
+      if (opts.browser === 'auto') {
+        for (const browser of SUPPORTED_BROWSERS) {
+          try {
+            const attempt = await extractAndValidateBrowser(browser, opts.profile);
+            attempts.push(attempt);
+            if (attempt.ok) {
+              result = attempt;
+              break;
+            }
+          } catch (e) {
+            attempts.push({
+              browser,
+              profile: opts.profile,
+              count: 0,
+              hasSession: false,
+              ok: false,
+              error: e.message,
+            });
+          }
+        }
+      } else {
+        result = await extractAndValidateBrowser(opts.browser, opts.profile);
+        attempts.push(result);
+      }
+
+      if (!result) {
+        result = { browser: opts.browser, profile: opts.profile, cookies: {}, count: 0, hasSession: false, ok: false };
+      }
+
+      const cookies = result.cookies;
       const count = Object.keys(cookies).length;
       spinner.text = `Found ${count} cookies. Testing auth...`;
 
@@ -110,20 +221,33 @@ program
       if (!hasSession) {
         spinner.stop();
         console.log(chalk.yellow(`⚠ Found ${count} cookies but no session token.`));
-        console.log('  Make sure you are logged into perplexity.ai in Chrome.');
-        if (count > 0) {
-          saveCookies(cookies);
-          console.log(chalk.dim('  Saved cookies anyway.'));
+        console.log('  Make sure you are logged into perplexity.ai in a supported browser.');
+        if (attempts.length) {
+          for (const attempt of attempts) {
+            const suffix = attempt.error ? ` (${attempt.error.split('\n')[0]})` : '';
+            console.log(chalk.dim(`  - ${attempt.browser}: ${attempt.count} cookies${suffix}`));
+          }
         }
+        console.log(chalk.dim('  Existing cookie file was left unchanged.'));
         return;
       }
 
-      const { cookies: refreshed } = await initSession(cookies);
-      saveCookies(refreshed);
-      spinner.succeed(`Extracted ${Object.keys(refreshed).length} cookies and saved to ~/.config/pplx/cookies.json`);
+      if (!result.ok) {
+        spinner.stop();
+        console.log(chalk.red(`✗ Found ${count} cookies in ${result.browser}, but they are invalid or expired.`));
+        if (attempts.length) {
+          for (const attempt of attempts) {
+            const status = attempt.ok ? 'valid' : (attempt.hasSession ? 'expired' : 'no session');
+            const suffix = attempt.error ? ` (${attempt.error.split('\n')[0]})` : '';
+            console.log(chalk.dim(`  - ${attempt.browser}: ${attempt.count} cookies, ${status}${suffix}`));
+          }
+        }
+        console.log(chalk.dim('  Existing cookie file was left unchanged.'));
+        process.exit(1);
+      }
 
-      const token = refreshed['__Secure-next-auth.session-token'] || refreshed['next-auth.session-token'];
-      console.log(chalk.dim(`  Session token: ${token?.slice(0, 20)}...`));
+      saveCookies(cookies);
+      finishSuccess(spinner, `Extracted ${Object.keys(cookies).length} cookies from ${result.browser} and saved to ~/.config/pplx/cookies.json`);
     } catch (e) {
       spinner.fail('Failed to extract cookies');
       console.error(chalk.red(e.message));
@@ -140,13 +264,27 @@ async function doSearch(query, opts) {
   opts = { ...cfg, ...opts };
   if (opts.curl) setUseCurl(true);
 
-  const cookies = loadCookies();
-  if (!cookies) {
+  const cookies = loadCookies() || {};
+  if (!opts.chrome && Object.keys(cookies).length === 0) {
     console.error(chalk.red('No cookies. Run: pplx auth'));
     process.exit(1);
   }
+  if (!opts.chrome && !opts.allowAnonymous) {
+    const ok = await testAuth(cookies);
+    if (!ok) {
+      console.error(chalk.red('Stored cookies are invalid or expired. Run: pplx auth --browser auto'));
+      process.exit(1);
+    }
+  }
 
   const mode = opts.mode || 'pro';
+  let timeoutMs;
+  try {
+    timeoutMs = resolveTimeoutMs({ ...opts, mode });
+  } catch (e) {
+    console.error(chalk.red(e.message));
+    process.exit(1);
+  }
   const sources = opts.sources ? opts.sources.split(',') : ['web'];
   const lang = opts.lang || 'en-US';
 
@@ -162,6 +300,9 @@ async function doSearch(query, opts) {
       language: lang,
       incognito: opts.incognito,
       chrome: opts.chrome,
+      playwright: opts.playwright,
+      curl: opts.curl,
+      timeoutMs,
     })) {
       lastData = data;
 
@@ -198,7 +339,7 @@ async function doSearch(query, opts) {
 
     if (!lastAnswer) {
       if (opts._spinner && !spinnerStopped) { opts._spinner.stop(); spinnerStopped = true; }
-      console.error(chalk.yellow('No answer received. Try re-authing (pplx auth) or use --curl.'));
+      console.error(chalk.yellow('No answer received. Try re-authing (pplx auth) or use --playwright/--curl.'));
       process.exit(1);
     }
 
@@ -209,7 +350,7 @@ async function doSearch(query, opts) {
   } catch (e) {
     console.error(chalk.red('\nError:'), e.message);
     if (e.message.includes('403')) {
-      console.log(chalk.yellow('Possible TLS fingerprinting block. Try: pplx search --curl "query"'));
+      console.log(chalk.yellow('Possible TLS fingerprinting block. Try: pplx search --curl "query" or --playwright'));
     }
     process.exit(1);
   }
@@ -230,6 +371,10 @@ program
   .option('--lang <code>', 'Language code', 'en-US')
   .option('--curl', 'Force curl-impersonate for TLS')
   .option('--chrome', 'Use Chrome CDP bridge instead of HTTP')
+  .option('--playwright', 'Use Playwright headless Chromium instead of HTTP')
+  .option('--no-playwright', 'Disable Playwright even if config enables it')
+  .option('--timeout-ms <duration>', 'Overall stream timeout: milliseconds by default, or use 120s / 10m')
+  .option('--allow-anonymous', 'Allow anonymous Perplexity responses when cookies are expired')
   .action(async (queryArg, opts) => {
     if (opts.raw) { rawMode = true; chalk.level = 0; }
     const query = await resolveQuery(queryArg);
@@ -244,6 +389,10 @@ program
   .option('--json', 'Output raw JSON')
   .option('--curl', 'Force curl-impersonate')
   .option('--chrome', 'Use Chrome CDP bridge')
+  .option('--playwright', 'Use Playwright headless Chromium')
+  .option('--no-playwright', 'Disable Playwright even if config enables it')
+  .option('--timeout-ms <duration>', 'Overall stream timeout: milliseconds by default, or use 120s / 10m')
+  .option('--allow-anonymous', 'Allow anonymous Perplexity responses when cookies are expired')
   .action(async (queryArg, opts) => {
     const query = await resolveQuery(queryArg);
     await doSearch(query, { ...opts, mode: 'reasoning' });
@@ -256,6 +405,10 @@ program
   .option('--json', 'Output raw JSON')
   .option('--curl', 'Force curl-impersonate')
   .option('--chrome', 'Use Chrome CDP bridge')
+  .option('--playwright', 'Use Playwright headless Chromium')
+  .option('--no-playwright', 'Disable Playwright even if config enables it')
+  .option('--timeout-ms <duration>', 'Overall stream timeout: milliseconds by default, or use 120s / 10m')
+  .option('--allow-anonymous', 'Allow anonymous Perplexity responses when cookies are expired')
   .action(async (queryArg, opts) => {
     const query = await resolveQuery(queryArg);
     const spinner = makeSpinner('Deep research in progress...').start();

package/src/cookies.js

@@ -20,27 +20,68 @@ export function saveCookies(cookies) {
   writeFileSync(COOKIES_FILE, JSON.stringify(cookies, null, 2));
 }
 
-function getChromeDir(profile) {
+export const BROWSER_SOURCES = {
+  chrome: {
+    label: 'Google Chrome',
+    root: () => join(homedir(), 'Library/Application Support/Google/Chrome'),
+    keychainService: 'Chrome Safe Storage',
+    keychainAccounts: ['Chrome', 'Google Chrome'],
+  },
+  'chrome-beta': {
+    label: 'Google Chrome Beta',
+    root: () => join(homedir(), 'Library/Application Support/Google/Chrome Beta'),
+    keychainService: 'Chrome Safe Storage',
+    keychainAccounts: ['Chrome', 'Google Chrome'],
+  },
+  comet: {
+    label: 'Comet',
+    root: () => join(homedir(), 'Library/Application Support/Comet'),
+    keychainService: 'Comet Safe Storage',
+    keychainAccounts: ['Comet'],
+  },
+  dia: {
+    label: 'Dia',
+    root: () => join(homedir(), 'Library/Application Support/Dia/User Data'),
+    keychainService: 'Dia Safe Storage',
+    keychainAccounts: ['Dia'],
+  },
+};
+
+export const SUPPORTED_BROWSERS = Object.keys(BROWSER_SOURCES);
+
+function getBrowserSource(browser = 'chrome') {
+  const source = BROWSER_SOURCES[browser];
+  if (!source) {
+    throw new Error(`Unsupported browser: ${browser}. Supported: ${SUPPORTED_BROWSERS.join(', ')}`);
+  }
+  return source;
+}
+
+function getChromeDir(profile, browser = 'chrome') {
   const platform = process.platform;
   if (platform === 'darwin') {
-    return join(homedir(), 'Library/Application Support/Google/Chrome', profile);
+    return join(getBrowserSource(browser).root(), profile);
   } else if (platform === 'linux') {
+    if (browser !== 'chrome') {
+      throw new Error(`Unsupported browser on Linux: ${browser}. Only chrome is supported.`);
+    }
     return join(homedir(), '.config/google-chrome', profile);
   }
   throw new Error(`Unsupported platform: ${platform}. Only macOS and Linux are supported.`);
 }
 
-function getChromeKey() {
+function getChromeKey(browser = 'chrome') {
   if (process.platform === 'linux') {
     return crypto.pbkdf2Sync('peanuts', 'saltysalt', 1, 16, 'sha1');
   }
   // macOS: Keychain
-  const accounts = ['Chrome', 'Google Chrome'];
+  const source = getBrowserSource(browser);
+  const accounts = source.keychainAccounts;
   let lastErr = null;
   for (const account of accounts) {
     try {
       const raw = execSync(
-        `security find-generic-password -w -s "Chrome Safe Storage" -a "${account}"`,
+        `security find-generic-password -w -s "${source.keychainService}" -a "${account}"`,
         { encoding: 'utf-8' }
       ).trim();
       if (raw) {
@@ -51,9 +92,9 @@ function getChromeKey() {
     }
   }
   const error = new Error(
-    'Keychain access denied for "Chrome Safe Storage". Run: ' +
-    'security find-generic-password -w -s "Chrome Safe Storage" -a "Chrome" ' +
-    '(or -a "Google Chrome") and allow access.'
+    `Keychain access denied for "${source.keychainService}". Run: ` +
+    `security find-generic-password -w -s "${source.keychainService}" -a "${accounts[0]}" ` +
+    'and allow access.'
   );
   if (lastErr) error.cause = lastErr;
   throw error;
@@ -90,8 +131,8 @@ function decryptValue(encrypted, key) {
   }
 }
 
-export function extractFromChrome(profile = 'Default') {
-  const chromeDir = getChromeDir(profile);
+export function extractFromChrome(profile = 'Default', browser = 'chrome') {
+  const chromeDir = getChromeDir(profile, browser);
   const cookieDb = join(chromeDir, 'Cookies');
 
   if (!existsSync(cookieDb)) {
@@ -110,16 +151,24 @@ export function extractFromChrome(profile = 'Default') {
   if (existsSync(walPath)) copyFileSync(walPath, tmpWal);
   if (existsSync(shmPath)) copyFileSync(shmPath, tmpShm);
 
-  const key = getChromeKey();
-  const db = new Database(tmpDb, { readonly: true });
+  const key = getChromeKey(browser);
+  let db;
+  try {
+    db = new Database(tmpDb, { readonly: true });
+  } catch (e) {
+    if (e.message.includes('NODE_MODULE_VERSION')) {
+      throw new Error(`${e.message}\nRun: npm rebuild better-sqlite3`);
+    }
+    throw e;
+  }
 
   const rows = db.prepare(
-    "SELECT name, encrypted_value FROM cookies WHERE host_key LIKE '%perplexity.ai'"
+    "SELECT name, value, encrypted_value FROM cookies WHERE host_key LIKE '%perplexity.ai' OR host_key LIKE '%perplexity.com'"
   ).all();
 
   const cookies = {};
   for (const row of rows) {
-    const val = decryptValue(row.encrypted_value, key);
+    const val = row.value || decryptValue(row.encrypted_value, key);
     if (val) cookies[row.name] = val;
   }
 

package/src/http.js

@@ -3,16 +3,98 @@
  */
 import { execSync, spawn } from 'child_process';
 import { PassThrough, Readable } from 'stream';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, rmSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
 import { withRetry } from './retry.js';
 
 let useCurl = false;
 let curlBinary = null;
+let warnedNoCurl = false;
+
+const CURL_IMPERSONATE_VERSION = 'v0.6.1';
+const CURL_IMPERSONATE_BASE = `https://github.com/lwthiker/curl-impersonate/releases/download/${CURL_IMPERSONATE_VERSION}`;
+const CURL_CACHE_DIR = join(homedir(), '.cache', 'pplx', 'curl-impersonate', CURL_IMPERSONATE_VERSION);
+const CURL_CANDIDATES = [
+  'curl-impersonate-chrome',
+  'curl_chrome120',
+  'curl_chrome116',
+  'curl_chrome110',
+  'curl_chrome107',
+  'curl_chrome104',
+  'curl_chrome101',
+  'curl_chrome100',
+  'curl_chrome99',
+];
 
 export function setUseCurl(val) { useCurl = val; }
 export function getUseCurl() { return useCurl; }
 
+function resolveCurlAsset() {
+  const platform = process.platform;
+  const arch = process.arch;
+  if (platform === 'linux') {
+    if (arch === 'x64') return `curl-impersonate-${CURL_IMPERSONATE_VERSION}.x86_64-linux-gnu.tar.gz`;
+    if (arch === 'arm64') return `curl-impersonate-${CURL_IMPERSONATE_VERSION}.aarch64-linux-gnu.tar.gz`;
+    if (arch === 'arm') return `curl-impersonate-${CURL_IMPERSONATE_VERSION}.arm-linux-gnueabihf.tar.gz`;
+  }
+  if (platform === 'darwin') {
+    if (arch === 'x64') return `curl-impersonate-${CURL_IMPERSONATE_VERSION}.x86_64-macos.tar.gz`;
+    if (arch === 'arm64') return `curl-impersonate-${CURL_IMPERSONATE_VERSION}.x86_64-macos.tar.gz`;
+  }
+  return null;
+}
+
+function findBinaryInDir(dir) {
+  for (const name of CURL_CANDIDATES) {
+    const p = join(dir, name);
+    if (existsSync(p)) return p;
+  }
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      if (entry.name.startsWith('curl_chrome') || entry.name.startsWith('curl-impersonate')) {
+        return join(dir, entry.name);
+      }
+    }
+  } catch {}
+  return null;
+}
+
+function downloadCurlImpersonate() {
+  const asset = resolveCurlAsset();
+  if (!asset) return false;
+
+  const binPath = join(CURL_CACHE_DIR, 'curl-impersonate-chrome');
+  if (existsSync(binPath)) return binPath;
+
+  const url = `${CURL_IMPERSONATE_BASE}/${asset}`;
+  const tmpDir = join(CURL_CACHE_DIR, `tmp-${Date.now()}`);
+  try {
+    mkdirSync(tmpDir, { recursive: true });
+    mkdirSync(CURL_CACHE_DIR, { recursive: true });
+    const tgz = join(tmpDir, asset);
+    execSync(`curl -L -o '${tgz}' '${url}'`, { stdio: 'ignore' });
+    execSync(`tar -xzf '${tgz}' -C '${tmpDir}'`, { stdio: 'ignore' });
+    const found = findBinaryInDir(tmpDir);
+    if (!found) return false;
+    copyFileSync(found, binPath);
+    chmodSync(binPath, 0o755);
+    return binPath;
+  } catch {
+    return false;
+  } finally {
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+  }
+}
+
 function findCurlImpersonate() {
   if (curlBinary !== null) return curlBinary;
+  const envPath = process.env.PPLX_CURL_IMPERSONATE;
+  if (envPath && existsSync(envPath)) {
+    curlBinary = envPath;
+    return curlBinary;
+  }
   for (const name of ['curl-impersonate-chrome', 'curl_chrome116', 'curl_chrome120']) {
     try {
       execSync(`which ${name}`, { stdio: 'pipe' });
@@ -20,6 +102,11 @@ function findCurlImpersonate() {
       return curlBinary;
     } catch {}
   }
+  const downloaded = downloadCurlImpersonate();
+  if (downloaded) {
+    curlBinary = downloaded;
+    return curlBinary;
+  }
   curlBinary = false;
   return false;
 }
@@ -54,8 +141,13 @@ export async function request(url, opts = {}) {
   // curl-impersonate fallback
   const bin = findCurlImpersonate();
   if (!bin) {
-    console.error('curl-impersonate not found. Install: brew install nicholasgasior/tap/curl-impersonate');
-    console.error('Falling back to native fetch...');
+    if (!warnedNoCurl) {
+      warnedNoCurl = true;
+      console.error('curl-impersonate not found.');
+      console.error('  Install: brew install nicholasgasior/tap/curl-impersonate');
+      console.error('  Or set PPLX_CURL_IMPERSONATE=/path/to/curl-impersonate-chrome');
+      console.error('  Falling back to native fetch...');
+    }
     return fetch(url, { ...opts, signal: opts.signal ?? AbortSignal.timeout(opts.timeout ?? 30000) });
   }
 
@@ -129,8 +221,13 @@ export async function streamingFetch(url, opts) {
 
   const bin = findCurlImpersonate();
   if (!bin) {
-    console.error('curl-impersonate not found. Install: https://github.com/lwthiker/curl-impersonate');
-    console.error('Falling back to native fetch...');
+    if (!warnedNoCurl) {
+      warnedNoCurl = true;
+      console.error('curl-impersonate not found.');
+      console.error('  Install: brew install nicholasgasior/tap/curl-impersonate');
+      console.error('  Or set PPLX_CURL_IMPERSONATE=/path/to/curl-impersonate-chrome');
+      console.error('  Falling back to native fetch...');
+    }
     return fetch(url, { ...opts, signal: opts.signal ?? AbortSignal.timeout(opts.timeout ?? 120000) });
   }
 

package/src/playwright-auth.js

@@ -0,0 +1,37 @@
+import { chromium } from 'playwright';
+import { BASE_URL, HEADERS } from './constants.js';
+import readline from 'readline';
+
+function waitForEnter(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+export async function extractFromPlaywright(opts = {}) {
+  const headless = opts.headless === true;
+  const browser = await chromium.launch({ headless });
+  const context = await browser.newContext({
+    userAgent: HEADERS['user-agent'],
+  });
+  const page = await context.newPage();
+  await page.goto(BASE_URL, { waitUntil: 'domcontentloaded' });
+
+  if (!headless) {
+    await waitForEnter('Log in to Perplexity in the opened browser, then press Enter here to continue...');
+  } else {
+    // Give headless a moment in case cookies are already present.
+    await page.waitForTimeout(3000);
+  }
+
+  const cookies = await context.cookies(BASE_URL);
+  await browser.close();
+
+  const out = {};
+  for (const c of cookies) out[c.name] = c.value;
+  return out;
+}

package/src/playwright-bridge.js

@@ -0,0 +1,116 @@
+import { chromium } from 'playwright';
+import { BASE_URL, HEADERS } from './constants.js';
+
+function toPlaywrightCookies(cookies) {
+  return Object.entries(cookies || {}).map(([name, value]) => ({
+    name,
+    value: String(value),
+    domain: '.perplexity.ai',
+    path: '/',
+    secure: name.startsWith('__Secure-') || name.startsWith('__Host-'),
+    httpOnly: false,
+    sameSite: 'Lax',
+  }));
+}
+
+export class PlaywrightBridge {
+  constructor(opts = {}) {
+    this.headless = opts.headless !== false;
+    this.cookies = opts.cookies || {};
+    this.browser = null;
+    this.context = null;
+    this.page = null;
+  }
+
+  async connect() {
+    this.browser = await chromium.launch({ headless: this.headless });
+    this.context = await this.browser.newContext({
+      userAgent: HEADERS['user-agent'],
+    });
+
+    const pwCookies = toPlaywrightCookies(this.cookies);
+    if (pwCookies.length > 0) {
+      await this.context.addCookies(pwCookies);
+    }
+
+    this.page = await this.context.newPage();
+    await this.page.goto(BASE_URL, { waitUntil: 'domcontentloaded' });
+  }
+
+  async evaluate(expression) {
+    return this.page.evaluate((expr) => eval(expr), expression);
+  }
+
+  /**
+   * Execute a streaming fetch — stores chunks in the page, polls them back.
+   * Returns an async generator of SSE text chunks.
+   */
+  async *fetchSSE(url, fetchOpts = {}) {
+    const storeId = '_pplx_' + Date.now();
+
+    await this.evaluate(`
+      (async () => {
+        window.${storeId} = { chunks: [], done: false, error: null, status: 0 };
+        try {
+          const r = await fetch(${JSON.stringify(url)}, ${JSON.stringify({
+            ...fetchOpts,
+            credentials: 'include',
+          })});
+          window.${storeId}.status = r.status;
+          if (!r.ok) {
+            window.${storeId}.error = 'HTTP ' + r.status + ': ' + (await r.text()).substring(0, 500);
+            window.${storeId}.done = true;
+            return;
+          }
+          const reader = r.body.getReader();
+          const decoder = new TextDecoder();
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            window.${storeId}.chunks.push(decoder.decode(value, { stream: true }));
+          }
+        } catch (e) {
+          window.${storeId}.error = e.message;
+        }
+        window.${storeId}.done = true;
+      })();
+      'started'
+    `);
+
+    const deadline = Date.now() + (fetchOpts.timeout ?? 120000);
+    await new Promise(r => setTimeout(r, 200));
+    try {
+      while (true) {
+        if (Date.now() > deadline) throw new Error('SSE polling timeout');
+        const stateJson = await this.evaluate(`
+          (() => {
+            const s = window['${storeId}'];
+            if (!s) return JSON.stringify({ chunks: [], done: true, error: 'store missing' });
+            const c = s.chunks.splice(0);
+            return JSON.stringify({ chunks: c, done: s.done, error: s.error, status: s.status });
+          })()
+        `);
+
+        const state = JSON.parse(stateJson);
+
+        if (state.error) {
+          throw new Error(state.error);
+        }
+
+        for (const chunk of state.chunks) {
+          yield chunk;
+        }
+
+        if (state.done) break;
+        await new Promise(r => setTimeout(r, 100));
+      }
+    } finally {
+      await this.evaluate(`delete window['${storeId}']`).catch(() => {});
+    }
+  }
+
+  async close() {
+    try { await this.context?.close(); } catch {}
+    try { await this.browser?.close(); } catch {}
+  }
+}

package/src/search.js

@@ -4,7 +4,7 @@ import { createParser } from 'eventsource-parser';
 import { BASE_URL, MODEL_MAP, HEADERS } from './constants.js';
 import { cookieHeader } from './cookies.js';
 import { initSession } from './session.js';
-import { request, streamingFetch } from './http.js';
+import { request, streamingFetch, getUseCurl, setUseCurl } from './http.js';
 import { withRetry } from './retry.js';
 
 export function resolveModelPref(mode, model) {
@@ -126,6 +126,7 @@ async function* searchWithChrome(query, cookies, opts) {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body,
+        timeout: opts.timeoutMs,
       }
     )) {
       parser.feed(chunk);
@@ -145,6 +146,58 @@ async function* searchWithChrome(query, cookies, opts) {
   }
 }
 
+async function* searchWithPlaywright(query, cookies, opts) {
+  const { PlaywrightBridge } = await import('./playwright-bridge.js');
+  const modelPref = resolveModelPref(opts.mode ?? 'auto', opts.model);
+  const body = buildSearchBody(query, opts, modelPref);
+  const bridge = new PlaywrightBridge({ headless: opts.playwrightHeadless !== false, cookies });
+  try {
+    await bridge.connect();
+
+    const results = [];
+    const parser = createParser({
+      onEvent(event) {
+        if (event.data === '{}' || !event.data) return;
+        try {
+          const json = JSON.parse(event.data);
+          parseNestedText(json);
+          results.push(json);
+        } catch (e) {
+          console.error(chalk.yellow('Warning: failed to parse SSE event'));
+          if (process.env.PPLX_VERBOSE) {
+            console.error('SSE parse error:', e.message);
+          }
+        }
+      }
+    });
+
+    let gotFinal = false;
+    for await (const chunk of bridge.fetchSSE(
+      `${BASE_URL}/rest/sse/perplexity_ask`,
+      {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        timeout: opts.timeoutMs,
+      }
+    )) {
+      parser.feed(chunk);
+      while (results.length > 0) {
+        const r = results.shift();
+        if (r.final_sse_message) gotFinal = true;
+        yield r;
+      }
+      if (gotFinal) break;
+    }
+
+    while (results.length > 0) {
+      yield results.shift();
+    }
+  } finally {
+    await bridge.close();
+  }
+}
+
 async function* searchWithHttp(query, cookies, opts) {
   const { cookies: sessionCookies, ok, status } = await initSession(cookies);
   if (!ok) {
@@ -168,6 +221,7 @@ async function* searchWithHttp(query, cookies, opts) {
       'cookie': cookieHeader(sessionCookies),
     },
     body,
+    timeout: opts.timeoutMs,
   });
 
   if (!resp.ok) {
@@ -230,7 +284,52 @@ export async function* search(query, cookies, opts = {}) {
     yield* searchWithChrome(query, cookies, opts);
     return;
   }
-  yield* searchWithHttp(query, cookies, opts);
+
+  const attempts = [];
+  if (opts.playwright) {
+    attempts.push({ name: 'playwright', run: () => searchWithPlaywright(query, cookies, opts) });
+    attempts.push({ name: 'curl', run: () => searchWithHttp(query, cookies, opts), curl: true });
+  } else if (opts.curl) {
+    attempts.push({ name: 'curl', run: () => searchWithHttp(query, cookies, opts), curl: true });
+  } else {
+    attempts.push({ name: 'http', run: () => searchWithHttp(query, cookies, opts) });
+    attempts.push({ name: 'playwright', run: () => searchWithPlaywright(query, cookies, opts) });
+    attempts.push({ name: 'curl', run: () => searchWithHttp(query, cookies, opts), curl: true });
+  }
+
+  const shouldFallbackHttp = (err) => {
+    const msg = (err?.message || '').toLowerCase();
+    return msg.includes('403') || msg.includes('tls') || msg.includes('cloudflare');
+  };
+
+  let lastErr = null;
+  for (let i = 0; i < attempts.length; i++) {
+    const attempt = attempts[i];
+    const isLast = i === attempts.length - 1;
+    const prevCurl = getUseCurl();
+    if (attempt.curl) setUseCurl(true);
+
+    let yielded = false;
+    try {
+      const gen = attempt.run();
+      for await (const item of gen) {
+        yielded = true;
+        yield item;
+      }
+      return;
+    } catch (e) {
+      lastErr = e;
+      if (attempt.name === 'http' && !shouldFallbackHttp(e)) throw e;
+      if (yielded || isLast) throw e;
+      if (process.env.PPLX_VERBOSE) {
+        console.error(`Search fallback: ${attempt.name} failed, trying next...`);
+      }
+    } finally {
+      if (attempt.curl) setUseCurl(prevCurl);
+    }
+  }
+
+  if (lastErr) throw lastErr;
 }
 
 export function parseNestedText(json) {

package/src/session.js

@@ -3,10 +3,28 @@ import { cookieHeader } from './cookies.js';
 import { request } from './http.js';
 import { withRetry } from './retry.js';
 
+function parseSessionPayload(text) {
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}
+
+export function isAuthenticatedSession(session) {
+  return Boolean(
+    session?.user?.email ||
+    session?.user?.id ||
+    session?.user?.name
+  );
+}
+
 export async function initSession(cookies) {
   const resp = await withRetry(() => request(`${BASE_URL}/api/auth/session`, {
     headers: {
       ...HEADERS,
+      accept: 'application/json',
       cookie: cookieHeader(cookies),
     },
     redirect: 'manual',
@@ -22,10 +40,18 @@ export async function initSession(cookies) {
     }
   }
 
-  return { cookies, status: resp.status, ok: resp.ok };
+  const text = await resp.text();
+  const session = parseSessionPayload(text);
+
+  return {
+    cookies,
+    status: resp.status,
+    ok: resp.ok && isAuthenticatedSession(session),
+    session,
+  };
 }
 
 export async function testAuth(cookies) {
-  const { status } = await initSession(cookies);
-  return status === 200;
+  const { ok } = await initSession(cookies);
+  return ok;
 }

package/src/timeout.js

@@ -0,0 +1,40 @@
+export const DEFAULT_SEARCH_TIMEOUT_MS = 120000;
+export const DEFAULT_RESEARCH_TIMEOUT_MS = 600000;
+
+export function parseTimeoutMs(value, label = 'timeout') {
+  if (value == null || value === '') return null;
+
+  if (typeof value === 'number') {
+    if (Number.isFinite(value) && value > 0) return Math.trunc(value);
+    throw new Error(`${label} must be a positive number of milliseconds`);
+  }
+
+  const text = String(value).trim().toLowerCase();
+  const match = text.match(/^(\d+(?:\.\d+)?)(ms|s|m)?$/);
+  if (!match) {
+    throw new Error(`${label} must be a positive duration like 120000, 120s, or 10m`);
+  }
+
+  const amount = Number(match[1]);
+  const unit = match[2] ?? 'ms';
+  const multipliers = { ms: 1, s: 1000, m: 60000 };
+  const timeoutMs = amount * multipliers[unit];
+
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(`${label} must be a positive duration`);
+  }
+
+  return Math.trunc(timeoutMs);
+}
+
+export function resolveTimeoutMs(opts = {}) {
+  const explicit = parseTimeoutMs(opts.timeoutMs, '--timeout-ms');
+  if (explicit != null) return explicit;
+
+  const configured = parseTimeoutMs(opts.timeout, 'config timeout');
+  if (configured != null) return configured;
+
+  return opts.mode === 'deep-research'
+    ? DEFAULT_RESEARCH_TIMEOUT_MS
+    : DEFAULT_SEARCH_TIMEOUT_MS;
+}