pplx-zero 2.0.0 → 2.1.0

package/README.md

@@ -1,46 +1,133 @@
 # pplx-zero
 
-Minimal Perplexity AI CLI - search from terminal.
+[![npm version](https://img.shields.io/npm/v/pplx-zero.svg)](https://www.npmjs.com/package/pplx-zero)
+[![AUR version](https://img.shields.io/aur/version/pplx-zero)](https://aur.archlinux.org/packages/pplx-zero)
+![Bun](https://img.shields.io/badge/runtime-bun-f9f1e1)
+![License](https://img.shields.io/badge/license-MIT-blue)
 
-## Installation
+Search the web with AI from your terminal. Zero bloat, maximum speed.
 
 ```bash
-bun install -g pplx-zero
+pplx "what is bun"
 ```
 
-Or with npm:
+## Why pplx-zero?
+
+- **Fast** — Bun-native, streams responses as they arrive
+- **Minimal** — ~400 lines of code, one dependency (zod)
+- **Powerful** — 5 models including deep research, file & image support
+- **Conversational** — Continue previous queries with `-c`
+- **Unix-friendly** — Pipes, JSON output, history, exit codes done right
+
+## Installation
 
 ```bash
+# Bun (recommended)
+bun install -g pplx-zero
+
+# npm (requires bun installed)
 npm install -g pplx-zero
+
+# Arch Linux
+yay -S pplx-zero
 ```
 
 ## Setup
 
+Get your API key from [Perplexity Settings](https://www.perplexity.ai/settings/api).
+
 ```bash
-export PERPLEXITY_API_KEY="your-api-key"
+export PERPLEXITY_API_KEY="pplx-..."
 ```
 
 ## 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"
+# Quick search
+pplx "best practices for error handling in typescript"
+
+# Use a more powerful model
+pplx -m sonar-pro "explain quantum entanglement simply"
+
+# Deep research mode (takes longer, more comprehensive)
+pplx -m sonar-deep-research "comprehensive analysis of AI regulation in 2024"
+
+# Analyze a document
+pplx -f report.pdf "summarize the key findings"
+
+# Describe an image
+pplx -i screenshot.png "what's happening in this image"
+
+# Continue a conversation
+pplx "what is rust"
+pplx -c "how does it compare to go?"
+pplx -c "which should I learn first?"
+
+# Save research to markdown
+pplx -m sonar-deep-research "AI trends 2025" -o research.md
+
+# Get JSON output for scripting
+pplx --json "capital of france" | jq .answer
+
+# View query history
+pplx --history
+
+# Search without saving to history
+pplx --no-history "sensitive query"
 ```
 
+## Models
+
+| Model | Best For |
+|-------|----------|
+| `sonar` | Quick answers (default) |
+| `sonar-pro` | Complex questions |
+| `sonar-reasoning` | Step-by-step thinking |
+| `sonar-reasoning-pro` | Advanced reasoning |
+| `sonar-deep-research` | Comprehensive research |
+
 ## 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.) |
+| `-m, --model <name>` | Select model |
+| `-f, --file <path>` | Attach document (PDF, TXT, MD, etc.) |
+| `-i, --image <path>` | Attach image (PNG, JPG, WebP, etc.) |
+| `-o, --output <path>` | Save output to file (.md, .txt) |
+| `-c, --continue` | Continue from last query |
+| `--history` | Show query history |
+| `--no-history` | Don't save query to history |
 | `--json` | Output as JSON |
 | `-h, --help` | Show help |
 
+## History & Sessions
+
+pplx-zero keeps a local history of your queries at `~/.pplx/history.jsonl`.
+
+```bash
+# View recent queries
+pplx --history
+
+# Filter with grep
+pplx --history | grep "typescript"
+
+# Continue last conversation
+pplx -c "tell me more"
+
+# Skip history for sensitive queries
+pplx --no-history "private question"
+```
+
+History auto-rotates at 1000 entries to keep the file small.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | API error |
+| `2` | Configuration error |
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pplx-zero",
-  "version": "2.0.0",
+  "version": "2.1.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,10 @@ 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';
 
 getEnv();
 
-
 const { values, positionals } = parseArgs({
   args: Bun.argv.slice(2),
   options: {
@@ -16,12 +16,16 @@ 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' },
   },
   allowPositionals: true,
   strict: true,
 });
 
-if (values.help || positionals.length === 0) {
+if (values.help) {
   console.log(`
 pplx - Perplexity AI search from terminal
 
@@ -31,6 +35,10 @@ 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
   --json               Output as JSON
   -h, --help           Show this help
 
@@ -38,18 +46,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 = '';
+let outputBuffer = '';
 
 if (!values.json) {
   await write(fmt.model(model) + ' ');
@@ -65,11 +107,12 @@ await search(query, model, {
   },
   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 +127,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/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> {