pplx-npx-search 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rajan Rengasamy
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# pplx-cli
+
+CLI for Perplexity AI with cookie-based authentication. Designed for headless/agent-first usage — no browser required at runtime.
+
+## Prerequisites
+
+- Node.js 20+
+- Google Chrome (only for initial cookie extraction via `pplx auth`)
+
+## Installation
+
+```bash
+git clone https://github.com/rajanrengasamy/pplx-cli.git
+cd pplx-cli
+npm install
+npm link
+```
+
+## Authentication
+
+Extract cookies from Chrome (one-time setup):
+
+```bash
+pplx auth
+pplx auth --test    # verify cookies work
+```
+
+Cookies are stored at `~/.config/pplx/cookies.json`.
+
+## Usage
+
+```bash
+# Search (default: pro mode, headless HTTP)
+pplx search "what is quantum computing"
+
+# Reasoning mode
+pplx reason "explain the Riemann hypothesis"
+
+# Deep research
+pplx research "compare React vs Vue in 2026"
+
+# Labs (free, no auth needed)
+pplx labs "hello world"
+
+# List models
+pplx models
+```
+
+### Options
+
+```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
+```
+
+## Agent/Automation Usage
+
+pplx-cli is designed to work in automated pipelines and with AI agents:
+
+```bash
+# Plain text output (no colors, no spinner)
+pplx search "query" --raw
+
+# 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)
+pplx search "query" | head -1
+
+# Non-zero exit code when no answer is returned
+pplx search "query" --json || echo "failed"
+```
+
+## 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
+
+## Configuration
+
+Optional config file at `~/.config/pplx/config.json`:
+
+```json
+{
+  "mode": "pro",
+  "model": "claude-3.5-sonnet",
+  "lang": "en-US"
+}
+```
+
+## 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.
+
+## License
+
+MIT

package/bin/pplx.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pplx-npx-search",
+  "version": "0.1.0",
+  "description": "CLI for Perplexity AI with cookie-based auth",
+  "type": "module",
+  "bin": {
+    "pplx": "./bin/pplx.js"
+  },
+  "scripts": {
+    "start": "node bin/pplx.js",
+    "test": "node --test test/**/*.test.js"
+  },
+  "keywords": [
+    "perplexity",
+    "ai",
+    "cli",
+    "search"
+  ],
+  "license": "MIT",
+  "author": "Rajan Rengasamy",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rajanrengasamy/pplx-cli"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "eventsource-parser": "^3.0.0",
+    "ora": "^8.0.0",
+    "ws": "^8.16.0"
+  }
+}

package/src/chrome-bridge.js

@@ -0,0 +1,183 @@
+/**
+ * Chrome CDP Bridge — executes fetch() inside Chrome's Perplexity tab
+ * to bypass Cloudflare TLS fingerprinting.
+ * 
+ * Connects via OpenClaw browser relay (ws://127.0.0.1:18793/cdp)
+ * or direct Chrome DevTools Protocol.
+ */
+import WebSocket from 'ws';
+
+const RELAY_URL = 'ws://127.0.0.1:18793/cdp';
+const RELAY_LIST = 'http://127.0.0.1:18793/json/list';
+const CDP_LIST = 'http://localhost:9222/json';
+
+export class ChromeBridge {
+  constructor() {
+    this.ws = null;
+    this.sessionId = null;
+    this.msgId = 0;
+    this.pending = new Map();
+  }
+
+  async connect() {
+    // Find the Perplexity tab
+    let tabs, wsUrl;
+    try {
+      const resp = await fetch(RELAY_LIST);
+      tabs = await resp.json();
+      wsUrl = RELAY_URL;
+    } catch {
+      try {
+        const resp = await fetch(CDP_LIST);
+        tabs = await resp.json();
+      } catch {
+        throw new Error(
+          'Cannot connect to Chrome.\n' +
+          '  Ensure OpenClaw gateway is running (openclaw gateway start)\n' +
+          '  and a Perplexity tab is open in Chrome.'
+        );
+      }
+    }
+
+    const pplxTab = tabs.find(t => t.url?.includes('perplexity.ai'));
+    if (!pplxTab) {
+      throw new Error(
+        'No Perplexity tab found in Chrome.\n' +
+        '  Open https://www.perplexity.ai/ in Chrome and try again.'
+      );
+    }
+
+    const targetId = pplxTab.id || pplxTab.targetId;
+    const connectUrl = wsUrl || pplxTab.webSocketDebuggerUrl;
+
+    await new Promise((resolve, reject) => {
+      this.ws = new WebSocket(connectUrl);
+      this.ws.on('open', resolve);
+      this.ws.on('message', (raw) => this._onMessage(raw));
+      this.ws.on('error', reject);
+      setTimeout(() => reject(new Error('WebSocket connect timeout')), 5000);
+    });
+
+    // Attach to the Perplexity tab
+    if (wsUrl === RELAY_URL) {
+      const resp = await this._sendAsync('Target.attachToTarget', {
+        targetId,
+        flatten: true,
+      });
+      this.sessionId = resp.result.sessionId;
+    }
+  }
+
+  _onMessage(raw) {
+    const msg = JSON.parse(raw.toString());
+    if (msg.id && this.pending.has(msg.id)) {
+      const { resolve, reject } = this.pending.get(msg.id);
+      this.pending.delete(msg.id);
+      if (msg.error) reject(new Error(msg.error.message));
+      else resolve(msg);
+    }
+  }
+
+  _sendAsync(method, params = {}, timeout = 60000) {
+    const id = ++this.msgId;
+    const msg = { id, method, params };
+    if (this.sessionId) msg.sessionId = this.sessionId;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.ws.send(JSON.stringify(msg));
+      setTimeout(() => {
+        if (this.pending.has(id)) {
+          this.pending.delete(id);
+          reject(new Error(`CDP timeout for ${method}`));
+        }
+      }, timeout);
+    });
+  }
+
+  /**
+   * Execute JavaScript in Chrome's Perplexity tab and return result.
+   */
+  async evaluate(expression, awaitPromise = true) {
+    const resp = await this._sendAsync('Runtime.evaluate', {
+      expression,
+      awaitPromise,
+      returnByValue: true,
+    });
+    if (resp.result?.exceptionDetails) {
+      const desc = resp.result.exceptionDetails.exception?.description || 'Unknown error';
+      throw new Error('Chrome eval error: ' + desc);
+    }
+    return resp.result?.result?.value;
+  }
+
+  /**
+   * Execute a streaming fetch — stores chunks in Chrome, polls them back.
+   * Returns an async generator of SSE text chunks.
+   */
+  async *fetchSSE(url, fetchOpts = {}) {
+    const storeId = '_pplx_' + Date.now();
+
+    // Start the fetch in Chrome
+    await this.evaluate(`
+      (async () => {
+        window.${storeId} = { chunks: [], done: false, error: null, status: 0 };
+        try {
+          const r = await fetch(${JSON.stringify(url)}, ${JSON.stringify(fetchOpts)});
+          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'
+    `, false); // Don't await — let it run in background
+
+    // Poll for chunks
+    const deadline = Date.now() + (fetchOpts.timeout ?? 120000);
+    await new Promise(r => setTimeout(r, 200)); // Give it a moment to start
+    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 });
+          })()
+        `, false);
+
+        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}']`, false).catch(() => {});
+    }
+  }
+
+  close() {
+    this.ws?.close();
+  }
+}

package/src/cli.js

@@ -0,0 +1,331 @@
+import { program } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { extractFromChrome, loadCookies, saveCookies, cookieHeader } from './cookies.js';
+import { initSession, testAuth } from './session.js';
+import { search } from './search.js';
+import { LabsClient } from './labs.js';
+import { formatSources } from './format.js';
+import { LABS_MODELS, MODEL_MAP } from './constants.js';
+import { setUseCurl } from './http.js';
+import { loadConfig } from './config.js';
+
+// --- Output state ---
+let rawMode = false;
+
+function isQuiet() {
+  return rawMode || !process.stdout.isTTY;
+}
+
+function makeSpinner(text) {
+  if (isQuiet()) {
+    // noop spinner
+    return { start() { return this; }, stop() {}, succeed() {}, fail() {}, text: '' };
+  }
+  return ora(text);
+}
+
+// --- Stdin helper ---
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data.trim()));
+    process.stdin.on('error', reject);
+  });
+}
+
+async function resolveQuery(queryArg) {
+  if (queryArg && queryArg !== '-') return queryArg;
+  if (queryArg === '-' || !process.stdin.isTTY) {
+    const input = await readStdin();
+    if (!input) {
+      console.error('Error: no query provided via stdin');
+      process.exit(1);
+    }
+    return input;
+  }
+  console.error('Error: no query provided');
+  process.exit(1);
+}
+
+// --- Program setup ---
+program
+  .name('pplx')
+  .description('CLI for Perplexity AI')
+  .version('0.1.0');
+
+program.option('--verbose', 'Enable verbose logging');
+program.option('--proxy <url>', 'Set proxy URL (sets HTTPS_PROXY env var)');
+program.option('--raw', 'Plain text output, no colors, no spinner');
+
+program.hook('preAction', (thisCmd) => {
+  const gopts = thisCmd.optsWithGlobals ? thisCmd.optsWithGlobals() : thisCmd.opts();
+  if (gopts.verbose) process.env.PPLX_VERBOSE = '1';
+  if (gopts.proxy) process.env.HTTPS_PROXY = gopts.proxy;
+  if (gopts.raw) {
+    rawMode = true;
+    chalk.level = 0;
+  }
+  if (!process.stdout.isTTY) {
+    chalk.level = 0;
+  }
+});
+
+// Auth command
+program
+  .command('auth')
+  .description('Extract and manage cookies from Chrome')
+  .option('--test', 'Test if stored cookies are valid')
+  .option('--profile <name>', 'Chrome profile', 'Default')
+  .action(async (opts) => {
+    if (opts.test) {
+      const cookies = loadCookies();
+      if (!cookies) {
+        console.log(chalk.red('No cookies stored. Run: pplx auth'));
+        process.exit(1);
+      }
+      const spinner = makeSpinner('Testing cookies...').start();
+      try {
+        const ok = await testAuth(cookies);
+        spinner.stop();
+        console.log(ok ? chalk.green('✓ Cookies are valid') : chalk.red('✗ Cookies are invalid or expired'));
+        process.exit(ok ? 0 : 1);
+      } catch (e) {
+        spinner.stop();
+        console.error(chalk.red('Error:'), e.message);
+        process.exit(1);
+      }
+      return;
+    }
+
+    const spinner = makeSpinner('Extracting cookies from Chrome...').start();
+    try {
+      const cookies = extractFromChrome(opts.profile);
+      const count = Object.keys(cookies).length;
+      spinner.text = `Found ${count} cookies. Testing auth...`;
+
+      const hasSession = cookies['next-auth.session-token'] || cookies['__Secure-next-auth.session-token'];
+      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.'));
+        }
+        return;
+      }
+
+      const { cookies: refreshed } = await initSession(cookies);
+      saveCookies(refreshed);
+      spinner.succeed(`Extracted ${Object.keys(refreshed).length} cookies and saved to ~/.config/pplx/cookies.json`);
+
+      const token = refreshed['__Secure-next-auth.session-token'] || refreshed['next-auth.session-token'];
+      console.log(chalk.dim(`  Session token: ${token?.slice(0, 20)}...`));
+    } catch (e) {
+      spinner.fail('Failed to extract cookies');
+      console.error(chalk.red(e.message));
+      if (e.message.includes('Keychain')) {
+        console.log(chalk.dim('  You may need to allow access in the Keychain prompt.'));
+      }
+      process.exit(1);
+    }
+  });
+
+// Shared search logic
+async function doSearch(query, opts) {
+  const cfg = loadConfig();
+  opts = { ...cfg, ...opts };
+  if (opts.curl) setUseCurl(true);
+
+  const cookies = loadCookies();
+  if (!cookies) {
+    console.error(chalk.red('No cookies. Run: pplx auth'));
+    process.exit(1);
+  }
+
+  const mode = opts.mode || 'pro';
+  const sources = opts.sources ? opts.sources.split(',') : ['web'];
+  const lang = opts.lang || 'en-US';
+
+  try {
+    let lastAnswer = '';
+    let lastData = null;
+    let spinnerStopped = false;
+
+    for await (const data of search(query, cookies, {
+      mode,
+      model: opts.model,
+      sources,
+      language: lang,
+      incognito: opts.incognito,
+      chrome: opts.chrome,
+    })) {
+      lastData = data;
+
+      if (opts.json) {
+        // For --json, we accumulate and output a single final object at the end
+        if (opts._spinner && !spinnerStopped) { opts._spinner.stop(); spinnerStopped = true; }
+        continue;
+      }
+
+      // Stream the answer diff
+      const answer = data.answer || '';
+      if (answer.length > lastAnswer.length) {
+        if (opts._spinner && !spinnerStopped) { opts._spinner.stop(); spinnerStopped = true; }
+        process.stdout.write(answer.slice(lastAnswer.length));
+        lastAnswer = answer;
+      }
+    }
+
+    if (opts.json) {
+      // Output single final JSON object
+      const answer = lastData?.answer || lastAnswer || '';
+      const webResults = lastData?.web_results || [];
+      const jsonOut = {
+        answer,
+        sources: webResults.map(r => ({ title: r.name || r.title, url: r.url })),
+        query,
+        mode,
+        model: opts.model || 'default',
+      };
+      console.log(JSON.stringify(jsonOut));
+      if (!answer) process.exit(1);
+      return;
+    }
+
+    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.'));
+      process.exit(1);
+    }
+
+    process.stdout.write('\n');
+    if (!rawMode && opts.citations !== false && lastData?.web_results) {
+      console.log(formatSources(lastData.web_results, { full: opts.citationsFull }));
+    }
+  } 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"'));
+    }
+    process.exit(1);
+  }
+}
+
+// Search command
+program
+  .command('search [query]')
+  .description('Search with Perplexity (default: pro mode)')
+  .option('-m, --mode <mode>', 'Search mode: auto, pro, reasoning, deep-research', 'pro')
+  .option('--model <model>', 'Model name or raw model ID (see pplx models)')
+  .option('--sources <sources>', 'Comma-separated: web,scholar,social', 'web')
+  .option('--json', 'Output single JSON object with answer, sources, query, mode, model')
+  .option('--raw', 'Plain text answer only (alias for global --raw)')
+  .option('--no-citations', 'Hide citation numbers and sources')
+  .option('--citations-full', 'Show full citation details (title + URL)')
+  .option('--incognito', 'Don\'t save to Perplexity history')
+  .option('--lang <code>', 'Language code', 'en-US')
+  .option('--curl', 'Force curl-impersonate for TLS')
+  .option('--chrome', 'Use Chrome CDP bridge instead of HTTP')
+  .action(async (queryArg, opts) => {
+    if (opts.raw) { rawMode = true; chalk.level = 0; }
+    const query = await resolveQuery(queryArg);
+    await doSearch(query, opts);
+  });
+
+// Shorthand: reason
+program
+  .command('reason [query]')
+  .description('Reasoning mode search')
+  .option('--model <model>', 'Model name')
+  .option('--json', 'Output raw JSON')
+  .option('--curl', 'Force curl-impersonate')
+  .option('--chrome', 'Use Chrome CDP bridge')
+  .action(async (queryArg, opts) => {
+    const query = await resolveQuery(queryArg);
+    await doSearch(query, { ...opts, mode: 'reasoning' });
+  });
+
+// Shorthand: research
+program
+  .command('research [query]')
+  .description('Deep research mode')
+  .option('--json', 'Output raw JSON')
+  .option('--curl', 'Force curl-impersonate')
+  .option('--chrome', 'Use Chrome CDP bridge')
+  .action(async (queryArg, opts) => {
+    const query = await resolveQuery(queryArg);
+    const spinner = makeSpinner('Deep research in progress...').start();
+    try {
+      await doSearch(query, { ...opts, mode: 'deep-research', _spinner: spinner });
+    } catch (e) {
+      spinner.fail(e.message);
+      process.exit(1);
+    }
+  });
+
+// Labs command
+program
+  .command('labs [query]')
+  .description('Query open-source models (no auth needed)')
+  .option('--model <model>', `Model: ${LABS_MODELS.join(', ')}`, 'sonar')
+  .option('--json', 'Output raw JSON')
+  .action(async (queryArg, opts) => {
+    const query = await resolveQuery(queryArg);
+    const spinner = makeSpinner('Connecting to labs...').start();
+    const client = new LabsClient();
+    try {
+      await client.connect();
+      spinner.stop();
+
+      let lastOutput = '';
+      for await (const data of client.ask(query, opts.model)) {
+        if (opts.json) {
+          console.log(JSON.stringify(data));
+          continue;
+        }
+        const output = data.output || '';
+        if (output.length > lastOutput.length) {
+          process.stdout.write(output.slice(lastOutput.length));
+          lastOutput = output;
+        }
+      }
+      if (!opts.json) process.stdout.write('\n');
+    } catch (e) {
+      spinner.fail('Labs error: ' + e.message);
+      process.exit(1);
+    } finally {
+      client.close();
+    }
+  });
+
+// Models command
+program
+  .command('models')
+  .description('List available models')
+  .action(() => {
+    for (const [mode, models] of Object.entries(MODEL_MAP)) {
+      console.log(chalk.bold(`\n${mode.charAt(0).toUpperCase() + mode.slice(1)} models:`));
+      for (const [name, id] of Object.entries(models)) {
+        console.log(`  ${name.padEnd(30)} ${chalk.dim(id)}`);
+      }
+    }
+    console.log(chalk.bold('\nLabs models:'), LABS_MODELS.join(', '));
+  });
+
+// Default: treat bare args as search
+program
+  .argument('[query...]', 'Quick search (shorthand for pplx search)')
+  .action(async (query) => {
+    if (query.length > 0) {
+      await doSearch(query.join(' '), {});
+    }
+  });
+
+program.parseAsync().catch((e) => {
+  console.error(e.message || e);
+  process.exit(1);
+});