pplx-zero 2.1.0 → 2.2.0

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/package.json

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

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;
+}