pplx-zero 2.1.0 → 2.2.1

package/README.md

@@ -1,133 +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>
 
-[![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)
+<h1 align="center">pplx</h1>
 
-Search the web with AI from your terminal. Zero bloat, maximum speed.
+<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
 pplx "what is bun"
 ```
 
-## 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
+Query [Perplexity AI](https://perplexity.ai) directly from your terminal. Responses stream in real-time with beautiful markdown formatting.
 
-## Installation
+## Features
 
-```bash
-# Bun (recommended)
-bun install -g pplx-zero
+- **⚡ 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
 
-# npm (requires bun installed)
-npm install -g pplx-zero
+## Install
 
-# Arch Linux
-yay -S pplx-zero
+```bash
+bun install -g pplx-zero    # recommended
+npm install -g pplx-zero    # requires bun
+yay -S pplx-zero            # arch linux
 ```
 
 ## Setup
 
-Get your API key from [Perplexity Settings](https://www.perplexity.ai/settings/api).
-
 ```bash
 export PERPLEXITY_API_KEY="pplx-..."
 ```
 
+Get your key at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)
+
 ## Usage
 
 ```bash
-# Quick search
-pplx "best practices for error handling in typescript"
+# search
+pplx "best typescript patterns 2025"
 
-# Use a more powerful model
-pplx -m sonar-pro "explain quantum entanglement simply"
+# models
+pplx -m sonar-pro "explain transformers"
+pplx -m sonar-deep-research "AI regulation analysis"
 
-# Deep research mode (takes longer, more comprehensive)
-pplx -m sonar-deep-research "comprehensive analysis of AI regulation in 2024"
+# conversation
+pplx "what is rust"
+pplx -c "compare to go"
 
-# Analyze a document
-pplx -f report.pdf "summarize the key findings"
+# files
+pplx -f paper.pdf "summarize"
+pplx -i diagram.png "explain this"
 
-# Describe an image
-pplx -i screenshot.png "what's happening in this image"
+# export
+pplx "topic" -o research.md
 
-# Continue a conversation
-pplx "what is rust"
-pplx -c "how does it compare to go?"
-pplx -c "which should I learn first?"
+# pretty markdown is default
+pplx "explain monads"
 
-# Save research to markdown
-pplx -m sonar-deep-research "AI trends 2025" -o research.md
+# raw output (no formatting)
+pplx --raw "explain monads"
 
-# Get JSON output for scripting
-pplx --json "capital of france" | jq .answer
-
-# View query history
+# history
 pplx --history
-
-# Search without saving to history
-pplx --no-history "sensitive query"
 ```
 
 ## Models
 
-| Model | Best For |
-|-------|----------|
-| `sonar` | Quick answers (default) |
+| Model | Use |
+|-------|-----|
+| `sonar` | Quick answers |
 | `sonar-pro` | Complex questions |
-| `sonar-reasoning` | Step-by-step thinking |
+| `sonar-reasoning` | Step-by-step |
 | `sonar-reasoning-pro` | Advanced reasoning |
-| `sonar-deep-research` | Comprehensive research |
+| `sonar-deep-research` | Research reports |
 
 ## Options
 
 | Flag | Description |
 |------|-------------|
-| `-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.
+| `-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 |
 
-## Exit Codes
+## Philosophy
 
-| Code | Meaning |
-|------|---------|
-| `0` | Success |
-| `1` | API error |
-| `2` | Configuration error |
+~400 lines. 1 dependency. No frameworks.
 
-## License
+---
 
-MIT
+<p align="center">MIT © <a href="https://github.com/codewithkenzo">kenzo</a></p>

package/bin/pplx.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 
-const { spawn, execSync } = require('child_process');
-const { join } = require('path');
+import { spawn, execSync } from 'child_process';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const hasBun = () => {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pplx-zero",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Minimal Perplexity AI CLI - search from terminal",
   "author": "kenzo",
   "license": "MIT",
@@ -25,7 +25,8 @@
   },
   "files": [
     "src",
-    "bin"
+    "bin",
+    "!src/**/*.test.ts"
   ],
   "repository": {
     "type": "git",

package/src/index.ts

@@ -5,6 +5,7 @@ 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();
 
@@ -20,6 +21,7 @@ const { values, positionals } = parseArgs({
     '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,
@@ -39,6 +41,7 @@ Options:
   -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
 
@@ -91,7 +94,7 @@ const file = filePath ? await encodeFile(filePath) : undefined;
 
 const startTime = Date.now();
 let fullContent = '';
-let outputBuffer = '';
+const mdState = createMarkdownState();
 
 if (!values.json) {
   await write(fmt.model(model) + ' ');
@@ -102,7 +105,8 @@ 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) => {

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/api.test.ts

@@ -1,21 +0,0 @@
-import { test, expect, describe } from 'bun:test';
-import { MODELS, type Model } from './api';
-
-describe('MODELS', () => {
-  test('includes all expected models', () => {
-    expect(MODELS).toContain('sonar');
-    expect(MODELS).toContain('sonar-pro');
-    expect(MODELS).toContain('sonar-reasoning');
-    expect(MODELS).toContain('sonar-reasoning-pro');
-    expect(MODELS).toContain('sonar-deep-research');
-  });
-
-  test('has exactly 5 models', () => {
-    expect(MODELS).toHaveLength(5);
-  });
-
-  test('Model type matches MODELS array', () => {
-    const model: Model = MODELS[0]!;
-    expect(MODELS.includes(model)).toBe(true);
-  });
-});

package/src/files.test.ts

@@ -1,71 +0,0 @@
-import { test, expect, describe } from 'bun:test';
-import { encodeFile, toDataUrl, type FileAttachment } from './files';
-import { writeFile, unlink } from 'node:fs/promises';
-import { join } from 'node:path';
-
-const TMP_DIR = '/tmp';
-
-describe('encodeFile', () => {
-  test('encodes text file correctly', async () => {
-    const testPath = join(TMP_DIR, 'test.txt');
-    await writeFile(testPath, 'hello world');
-    
-    const result = await encodeFile(testPath);
-    
-    expect(result.type).toBe('file');
-    expect(result.mimeType).toBe('text/plain');
-    expect(result.filename).toBe('test.txt');
-    expect(result.data).toBe(Buffer.from('hello world').toString('base64'));
-    
-    await unlink(testPath);
-  });
-
-  test('encodes PDF as file type', async () => {
-    const testPath = join(TMP_DIR, 'test.pdf');
-    await writeFile(testPath, '%PDF-1.4 test');
-    
-    const result = await encodeFile(testPath);
-    
-    expect(result.type).toBe('file');
-    expect(result.mimeType).toBe('application/pdf');
-    
-    await unlink(testPath);
-  });
-
-  test('encodes PNG as image type', async () => {
-    const testPath = join(TMP_DIR, 'test.png');
-    const pngHeader = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
-    await writeFile(testPath, pngHeader);
-    
-    const result = await encodeFile(testPath);
-    
-    expect(result.type).toBe('image');
-    expect(result.mimeType).toBe('image/png');
-    
-    await unlink(testPath);
-  });
-
-  test('throws on unsupported file type', async () => {
-    const testPath = join(TMP_DIR, 'test.xyz');
-    await writeFile(testPath, 'test');
-    
-    await expect(encodeFile(testPath)).rejects.toThrow('Unsupported file type: .xyz');
-    
-    await unlink(testPath);
-  });
-});
-
-describe('toDataUrl', () => {
-  test('creates valid data URL', () => {
-    const attachment: FileAttachment = {
-      type: 'image',
-      data: 'aGVsbG8gd29ybGQ=',
-      mimeType: 'image/png',
-      filename: 'test.png',
-    };
-    
-    const result = toDataUrl(attachment);
-    
-    expect(result).toBe('data:image/png;base64,aGVsbG8gd29ybGQ=');
-  });
-});

package/src/history.test.ts

@@ -1,84 +0,0 @@
-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/output.test.ts

@@ -1,41 +0,0 @@
-import { test, expect, describe } from 'bun:test';
-import { fmt } from './output';
-
-describe('fmt', () => {
-  test('model formats with cyan color', () => {
-    const result = fmt.model('sonar');
-    expect(result).toContain('[sonar]');
-    expect(result).toContain('\x1b[36m');
-    expect(result).toContain('\x1b[0m');
-  });
-
-  test('searching shows dim text', () => {
-    const result = fmt.searching();
-    expect(result).toContain('Searching...');
-    expect(result).toContain('\x1b[2m');
-  });
-
-  test('error formats with red color', () => {
-    const result = fmt.error('test error');
-    expect(result).toContain('Error: test error');
-    expect(result).toContain('\x1b[31m');
-  });
-
-  test('citation formats with number and URL', () => {
-    const result = fmt.citation(1, 'https://example.com');
-    expect(result).toContain('1.');
-    expect(result).toContain('https://example.com');
-  });
-
-  test('stats formats tokens and time', () => {
-    const result = fmt.stats(100, 1500);
-    expect(result).toContain('100 tokens');
-    expect(result).toContain('1.5s');
-  });
-
-  test('sources shows yellow header', () => {
-    const result = fmt.sources();
-    expect(result).toContain('Sources:');
-    expect(result).toContain('\x1b[33m');
-  });
-});