pplx-zero 2.0.0 → 2.2.0

package/README.md

@@ -1,46 +1,112 @@
-# pplx-zero
+<p align="center">
+  <img src="https://raw.githubusercontent.com/codewithkenzo/pplx-zero/main/logo.png" alt="pplx-zero" width="140" />
+</p>
 
-Minimal Perplexity AI CLI - search from terminal.
+<h1 align="center">pplx</h1>
 
-## Installation
+<p align="center">
+  <strong>AI search from your terminal. Zero bloat.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/pplx-zero"><img src="https://img.shields.io/npm/v/pplx-zero.svg?color=00d4ff" alt="npm"></a>
+  <a href="https://aur.archlinux.org/packages/pplx-zero"><img src="https://img.shields.io/aur/version/pplx-zero?color=00d4ff" alt="AUR"></a>
+  <img src="https://img.shields.io/badge/bun-runtime-f9f1e1" alt="Bun">
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License">
+</p>
+
+---
 
 ```bash
-bun install -g pplx-zero
+pplx "what is bun"
 ```
 
-Or with npm:
+Query [Perplexity AI](https://perplexity.ai) directly from your terminal. Responses stream in real-time with beautiful markdown formatting.
+
+## Features
+
+- **⚡ Streaming** — Answers appear as they're generated
+- **💬 Conversations** — Continue with `-c` for multi-turn
+- **📄 Documents** — Analyze PDFs, code, text files
+- **🖼️ Images** — Describe screenshots and diagrams
+- **📝 Export** — Save research to markdown
+- **🎨 Pretty** — Rendered markdown by default
+- **🕐 History** — Browse and search past queries
+
+## Install
 
 ```bash
-npm install -g pplx-zero
+bun install -g pplx-zero    # recommended
+npm install -g pplx-zero    # requires bun
+yay -S pplx-zero            # arch linux
 ```
 
 ## Setup
 
 ```bash
-export PERPLEXITY_API_KEY="your-api-key"
+export PERPLEXITY_API_KEY="pplx-..."
 ```
 
+Get your key at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)
+
 ## Usage
 
 ```bash
-pplx "what is bun"
-pplx -m sonar-pro "explain quantum computing"
-pplx -m sonar-deep-research "comprehensive analysis of AI trends"
-pplx -f report.pdf "summarize this document"
-pplx -i screenshot.png "what's in this image"
-pplx --json "get structured response"
+# search
+pplx "best typescript patterns 2025"
+
+# models
+pplx -m sonar-pro "explain transformers"
+pplx -m sonar-deep-research "AI regulation analysis"
+
+# conversation
+pplx "what is rust"
+pplx -c "compare to go"
+
+# files
+pplx -f paper.pdf "summarize"
+pplx -i diagram.png "explain this"
+
+# export
+pplx "topic" -o research.md
+
+# pretty markdown is default
+pplx "explain monads"
+
+# raw output (no formatting)
+pplx --raw "explain monads"
+
+# history
+pplx --history
 ```
 
+## Models
+
+| Model | Use |
+|-------|-----|
+| `sonar` | Quick answers |
+| `sonar-pro` | Complex questions |
+| `sonar-reasoning` | Step-by-step |
+| `sonar-reasoning-pro` | Advanced reasoning |
+| `sonar-deep-research` | Research reports |
+
 ## Options
 
 | Flag | Description |
 |------|-------------|
-| `-m, --model` | Model: sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, sonar-deep-research |
-| `-f, --file` | Attach a file (PDF, TXT, etc.) |
-| `-i, --image` | Attach an image (PNG, JPG, etc.) |
-| `--json` | Output as JSON |
-| `-h, --help` | Show help |
+| `-m` | Model selection |
+| `-f` | Attach file |
+| `-i` | Attach image |
+| `-o` | Output to file |
+| `-c` | Continue conversation |
+| `--raw` | Raw output (no markdown) |
+| `--history` | View history |
+| `--json` | JSON output |
+
+## Philosophy
+
+~400 lines. 1 dependency. No frameworks.
 
-## License
+---
 
-MIT
+<p align="center">MIT © <a href="https://github.com/codewithkenzo">kenzo</a></p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pplx-zero",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Minimal Perplexity AI CLI - search from terminal",
   "author": "kenzo",
   "license": "MIT",

package/src/history.test.ts

@@ -0,0 +1,84 @@
+import { test, expect, beforeEach, afterAll } from 'bun:test';
+import { appendHistory, readHistory, getLastEntry, clearHistory } from './history';
+
+beforeEach(async () => {
+  await clearHistory();
+});
+
+afterAll(async () => {
+  await clearHistory();
+});
+
+test('appendHistory creates entry', async () => {
+  await appendHistory({ q: 'test query', m: 'sonar', a: 'test answer' });
+  const entries = await readHistory();
+  expect(entries.length).toBe(1);
+  expect(entries[0]!.q).toBe('test query');
+  expect(entries[0]!.m).toBe('sonar');
+  expect(entries[0]!.a).toBe('test answer');
+  expect(entries[0]!.ts).toBeGreaterThan(0);
+});
+
+test('readHistory returns entries in reverse order', async () => {
+  await appendHistory({ q: 'first', m: 'sonar', a: 'a1' });
+  await appendHistory({ q: 'second', m: 'sonar-pro', a: 'a2' });
+  await appendHistory({ q: 'third', m: 'sonar', a: 'a3' });
+  
+  const entries = await readHistory();
+  expect(entries.length).toBe(3);
+  expect(entries[0]!.q).toBe('third');
+  expect(entries[1]!.q).toBe('second');
+  expect(entries[2]!.q).toBe('first');
+});
+
+test('readHistory respects limit', async () => {
+  await appendHistory({ q: 'one', m: 'sonar', a: 'a' });
+  await appendHistory({ q: 'two', m: 'sonar', a: 'a' });
+  await appendHistory({ q: 'three', m: 'sonar', a: 'a' });
+  
+  const entries = await readHistory(2);
+  expect(entries.length).toBe(2);
+  expect(entries[0]!.q).toBe('three');
+  expect(entries[1]!.q).toBe('two');
+});
+
+test('getLastEntry returns most recent', async () => {
+  await appendHistory({ q: 'old', m: 'sonar', a: 'old answer' });
+  await appendHistory({ q: 'new', m: 'sonar-pro', a: 'new answer' });
+  
+  const last = await getLastEntry();
+  expect(last?.q).toBe('new');
+  expect(last?.m).toBe('sonar-pro');
+});
+
+test('getLastEntry returns null when empty', async () => {
+  const last = await getLastEntry();
+  expect(last).toBeNull();
+});
+
+test('clearHistory removes all entries', async () => {
+  await appendHistory({ q: 'test', m: 'sonar', a: 'answer' });
+  await clearHistory();
+  const entries = await readHistory();
+  expect(entries.length).toBe(0);
+});
+
+test('appendHistory stores citations', async () => {
+  await appendHistory({ 
+    q: 'query', 
+    m: 'sonar', 
+    a: 'answer',
+    citations: ['https://example.com', 'https://test.com']
+  });
+  
+  const entries = await readHistory();
+  expect(entries[0]!.citations).toEqual(['https://example.com', 'https://test.com']);
+});
+
+test('appendHistory truncates long answers', async () => {
+  const longAnswer = 'x'.repeat(3000);
+  await appendHistory({ q: 'query', m: 'sonar', a: longAnswer });
+  
+  const entries = await readHistory();
+  expect(entries[0]!.a.length).toBe(2000);
+});

package/src/history.ts

@@ -0,0 +1,86 @@
+import type { Model } from './api';
+
+export interface HistoryEntry {
+  ts: number;
+  q: string;
+  m: Model;
+  a: string;
+  citations?: string[];
+}
+
+const HISTORY_DIR = `${process.env.HOME}/.pplx`;
+const HISTORY_PATH = `${HISTORY_DIR}/history.jsonl`;
+const MAX_ENTRIES = 1000;
+const MAX_ANSWER_LENGTH = 2000;
+
+async function ensureDir(): Promise<void> {
+  const dir = Bun.file(HISTORY_DIR);
+  if (!(await dir.exists())) {
+    await Bun.$`mkdir -p ${HISTORY_DIR}`;
+  }
+}
+
+export async function appendHistory(entry: Omit<HistoryEntry, 'ts'>): Promise<void> {
+  await ensureDir();
+  
+  const file = Bun.file(HISTORY_PATH);
+  const exists = await file.exists();
+  
+  if (exists) {
+    const text = await file.text();
+    const lines = text.trim().split('\n').filter(l => l.length > 0);
+    if (lines.length >= MAX_ENTRIES) {
+      const keep = lines.slice(-MAX_ENTRIES + 1).join('\n') + '\n';
+      await Bun.write(HISTORY_PATH, keep);
+    }
+  }
+  
+  const record: HistoryEntry = {
+    ts: Date.now(),
+    q: entry.q,
+    m: entry.m,
+    a: entry.a.slice(0, MAX_ANSWER_LENGTH),
+    ...(entry.citations?.length ? { citations: entry.citations } : {}),
+  };
+  
+  const line = JSON.stringify(record) + '\n';
+  
+  if (exists) {
+    const current = await Bun.file(HISTORY_PATH).text();
+    await Bun.write(HISTORY_PATH, current + line);
+  } else {
+    await Bun.write(HISTORY_PATH, line);
+  }
+}
+
+export async function readHistory(limit = 20): Promise<HistoryEntry[]> {
+  const file = Bun.file(HISTORY_PATH);
+  if (!(await file.exists())) return [];
+  
+  const text = await file.text();
+  const lines = text.trim().split('\n').filter(l => l.length > 0);
+  
+  return lines
+    .map(line => {
+      try {
+        return JSON.parse(line) as HistoryEntry;
+      } catch {
+        return null;
+      }
+    })
+    .filter((e): e is HistoryEntry => e !== null)
+    .reverse()
+    .slice(0, limit);
+}
+
+export async function getLastEntry(): Promise<HistoryEntry | null> {
+  const entries = await readHistory(1);
+  return entries[0] ?? null;
+}
+
+export async function clearHistory(): Promise<void> {
+  const file = Bun.file(HISTORY_PATH);
+  if (await file.exists()) {
+    await Bun.write(HISTORY_PATH, '');
+  }
+}

package/src/index.ts

@@ -4,10 +4,11 @@ import { search, MODELS, type Model } from './api';
 import { encodeFile } from './files';
 import { getEnv } from './env';
 import { fmt, write, writeLn } from './output';
+import { appendHistory, readHistory, getLastEntry } from './history';
+import { renderMarkdown, createMarkdownState } from './markdown';
 
 getEnv();
 
-
 const { values, positionals } = parseArgs({
   args: Bun.argv.slice(2),
   options: {
@@ -16,12 +17,17 @@ const { values, positionals } = parseArgs({
     image: { type: 'string', short: 'i' },
     json: { type: 'boolean', default: false },
     help: { type: 'boolean', short: 'h' },
+    history: { type: 'boolean', default: false },
+    'no-history': { type: 'boolean', default: false },
+    continue: { type: 'boolean', short: 'c', default: false },
+    output: { type: 'string', short: 'o' },
+    raw: { type: 'boolean', default: false },
   },
   allowPositionals: true,
   strict: true,
 });
 
-if (values.help || positionals.length === 0) {
+if (values.help) {
   console.log(`
 pplx - Perplexity AI search from terminal
 
@@ -31,6 +37,11 @@ Options:
   -m, --model <name>   Model: ${MODELS.join(', ')} (default: sonar)
   -f, --file <path>    Attach a file (PDF, TXT, etc.)
   -i, --image <path>   Attach an image (PNG, JPG, etc.)
+  -o, --output <path>  Save output to file (.md, .txt)
+  -c, --continue       Continue from last query (add context)
+  --history            Show query history
+  --no-history         Don't save this query to history
+  --raw                Raw output (no markdown rendering)
   --json               Output as JSON
   -h, --help           Show this help
 
@@ -38,18 +49,52 @@ Examples:
   pplx "what is bun"
   pplx -m sonar-pro "explain quantum computing"
   pplx -f report.pdf "summarize this document"
+  pplx -c "tell me more about that"
+  pplx --history | grep "bun"
 `);
   process.exit(0);
 }
 
-const query = positionals.join(' ');
+if (values.history) {
+  const entries = await readHistory(20);
+  if (entries.length === 0) {
+    console.log('No history yet.');
+  } else {
+    for (const entry of entries) {
+      console.log(fmt.historyEntry(entry.ts, entry.m, entry.q));
+    }
+  }
+  process.exit(0);
+}
+
+if (positionals.length === 0 && !values.continue) {
+  console.error(fmt.error('No query provided. Use -h for help.'));
+  process.exit(2);
+}
+
+let query = positionals.join(' ');
 const model = (MODELS.includes(values.model as Model) ? values.model : 'sonar') as Model;
 
+if (values.continue) {
+  const last = await getLastEntry();
+  if (last) {
+    const context = `Previous question: "${last.q}"\nPrevious answer: "${last.a.slice(0, 500)}..."\n\nFollow-up question: ${query || 'Continue and elaborate on the previous answer.'}`;
+    query = context;
+    if (!values.json) {
+      await write(fmt.continuing(last.q));
+    }
+  } else if (!query) {
+    console.error(fmt.error('No previous query to continue from.'));
+    process.exit(2);
+  }
+}
+
 const filePath = values.file || values.image;
 const file = filePath ? await encodeFile(filePath) : undefined;
 
 const startTime = Date.now();
 let fullContent = '';
+const mdState = createMarkdownState();
 
 if (!values.json) {
   await write(fmt.model(model) + ' ');
@@ -60,16 +105,18 @@ await search(query, model, {
   onContent: async (text) => {
     fullContent += text;
     if (!values.json) {
-      await write(text);
+      const out = values.raw ? text : renderMarkdown(text, mdState);
+      await write(out);
     }
   },
   onDone: async (citations, usage) => {
     const elapsed = Date.now() - startTime;
+    const citationUrls = citations.map((c) => c.url);
 
     if (values.json) {
       const output = {
         answer: fullContent,
-        citations: citations.map((c) => c.url),
+        citations: citationUrls,
         model,
         tokens: usage.prompt_tokens + usage.completion_tokens,
         latency_ms: elapsed,
@@ -84,6 +131,46 @@ await search(query, model, {
       }
       await write(fmt.stats(usage.prompt_tokens + usage.completion_tokens, elapsed));
     }
+
+    if (values.output) {
+      const ext = values.output.split('.').pop()?.toLowerCase();
+      let content = '';
+      
+      if (ext === 'md') {
+        content = `# ${positionals.join(' ') || 'Query'}\n\n`;
+        content += `**Model:** ${model}\n`;
+        content += `**Date:** ${new Date().toISOString()}\n\n`;
+        content += `## Answer\n\n${fullContent}\n\n`;
+        if (citationUrls.length > 0) {
+          content += `## Sources\n\n`;
+          citationUrls.forEach((url, i) => {
+            content += `${i + 1}. ${url}\n`;
+          });
+        }
+      } else {
+        content = fullContent;
+        if (citationUrls.length > 0) {
+          content += '\n\nSources:\n';
+          citationUrls.forEach((url, i) => {
+            content += `${i + 1}. ${url}\n`;
+          });
+        }
+      }
+      
+      await Bun.write(values.output, content);
+      if (!values.json) {
+        await writeLn(`\n${fmt.model('saved')} ${values.output}`);
+      }
+    }
+
+    if (!values['no-history'] && !values.json) {
+      await appendHistory({
+        q: positionals.join(' ') || '(continued)',
+        m: model,
+        a: fullContent,
+        citations: citationUrls,
+      });
+    }
   },
   onError: async (error) => {
     if (values.json) {

package/src/markdown.ts

@@ -0,0 +1,64 @@
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m',
+  magenta: '\x1b[35m',
+  gray: '\x1b[90m',
+  bgBlue: '\x1b[44m',
+} as const;
+
+export interface MarkdownState {
+  inCode: boolean;
+  codeLanguage: string;
+}
+
+export function createMarkdownState(): MarkdownState {
+  return { inCode: false, codeLanguage: '' };
+}
+
+export function renderMarkdown(chunk: string, state: MarkdownState): string {
+  let out = chunk;
+
+  const fenceMatch = out.match(/```(\w*)/);
+  if (fenceMatch) {
+    state.inCode = !state.inCode;
+    state.codeLanguage = fenceMatch[1] || '';
+    out = out.replace(/```\w*/g, state.inCode ? `${c.yellow}━━━ ${state.codeLanguage || 'code'} ━━━${c.reset}` : `${c.yellow}━━━━━━━━━━━${c.reset}`);
+    return out;
+  }
+
+  if (state.inCode) {
+    return `${c.dim}${out}${c.reset}`;
+  }
+
+  if (out.startsWith('### ')) {
+    return `${c.bold}${c.cyan}${out.slice(4)}${c.reset}`;
+  }
+  if (out.startsWith('## ')) {
+    return `${c.bold}${c.magenta}${out.slice(3)}${c.reset}`;
+  }
+  if (out.startsWith('# ')) {
+    return `${c.bold}${c.cyan}▸ ${out.slice(2)}${c.reset}`;
+  }
+
+  if (out.startsWith('> ')) {
+    return `${c.italic}${c.gray}│ ${out.slice(2)}${c.reset}`;
+  }
+
+  if (out.match(/^[\-\*] /)) {
+    out = out.replace(/^[\-\*] /, `${c.cyan}• ${c.reset}`);
+  }
+  if (out.match(/^\d+\. /)) {
+    out = out.replace(/^(\d+)\. /, `${c.cyan}$1.${c.reset} `);
+  }
+
+  out = out
+    .replace(/\*\*([^*]+)\*\*/g, `${c.bold}$1${c.reset}`)
+    .replace(/\*([^*]+)\*/g, `${c.italic}$1${c.reset}`)
+    .replace(/`([^`]+)`/g, `${c.bgBlue} $1 ${c.reset}`);
+
+  return out;
+}

package/src/output.ts

@@ -17,6 +17,13 @@ export const fmt = {
   stats: (tokens: number, ms: number) => 
     `\n${c.gray}[${tokens} tokens, ${(ms / 1000).toFixed(1)}s]${c.reset}\n`,
   sources: () => `\n${c.yellow}Sources:${c.reset}`,
+  historyEntry: (ts: number, model: string, query: string) => {
+    const date = new Date(ts).toLocaleString('en-US', { 
+      month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' 
+    });
+    return `${c.dim}${date}${c.reset} ${c.cyan}[${model}]${c.reset} ${query}`;
+  },
+  continuing: (query: string) => `${c.dim}Continuing from:${c.reset} ${query.slice(0, 50)}${query.length > 50 ? '...' : ''}\n`,
 };
 
 export async function write(text: string): Promise<void> {