@vibemastery/zurf 0.2.2 → 0.3.0

package/README.md

@@ -1,47 +1,194 @@
 zurf
 =================
 
-A lightweight CLI for searching and fetching web pages, powered by Browserbase.
+A lightweight CLI for searching, browsing, and fetching web pages (Browserbase) and asking AI-powered questions with web citations (Perplexity Sonar).
 
 
 [![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
 [![Version](https://img.shields.io/npm/v/@vibemastery/zurf.svg)](https://npmjs.org/package/@vibemastery/zurf)
 [![Downloads/week](https://img.shields.io/npm/dw/@vibemastery/zurf.svg)](https://npmjs.org/package/@vibemastery/zurf)
 
+## Installation
+
+```sh-session
+$ npm install -g @vibemastery/zurf
+$ zurf setup                       # configure API keys (Browserbase, Perplexity)
+$ zurf --help
+```
+
+## Commands
+
+### `zurf ask <question>`
+
+Ask a question and get an AI-powered answer with web citations via Perplexity Sonar. Use `--depth deep` for more thorough research (sonar-pro).
+
+```sh-session
+$ zurf ask "What is Browserbase?"
+$ zurf ask "latest tech news" --recency day
+$ zurf ask "search reddit for best CLI tools" --domains reddit.com
+$ zurf ask "explain quantum computing" --depth deep
+$ zurf ask "What is Node.js?" --json
+$ zurf ask "What is oclif?" --no-citations
+```
+
+| Flag | Description |
+|------|-------------|
+| `--depth <quick\|deep>` | Search depth: quick (sonar) or deep (sonar-pro). Default: quick |
+| `--recency <hour\|day\|week\|month\|year>` | Filter sources by recency |
+| `--domains <list>` | Restrict search to these domains (comma-separated) |
+| `--no-citations` | Hide the sources list after the answer |
+| `--json` | Print machine-readable JSON to stdout |
+
+### `zurf search <query>`
+
+Search the web via Browserbase (Exa-powered). Returns a list of matching URLs with titles and snippets.
+
+```sh-session
+$ zurf search "browserbase documentation"
+$ zurf search "laravel inertia" --num-results 5 --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `-n, --num-results` | Number of results, 1-25 (default: 10) |
+| `--json` | Print machine-readable JSON to stdout |
+
+### `zurf browse <url>`
+
+Open a URL in a real cloud Chromium browser via Browserbase, wait for JavaScript to fully render, then return the page content as **markdown** (default) or raw HTML.
+
+Best for JavaScript-heavy pages (SPAs, dashboards, pages behind client-side rendering).
+
+```sh-session
+$ zurf browse https://example.com              # markdown output
+$ zurf browse https://example.com --html       # raw HTML output
+$ zurf browse https://example.com -o page.md   # save full content to file
+$ zurf browse https://example.com --json       # JSON with content + metadata
+```
+
+| Flag | Description |
+|------|-------------|
+| `--html` | Output raw HTML instead of markdown |
+| `-o, --output` | Write full content to a file |
+| `--json` | Print machine-readable JSON to stdout |
+
+### `zurf fetch <url>`
+
+Fetch a URL via Browserbase without launching a full browser session. Returns the content as **markdown** (default) or raw HTML. Fast and lightweight, but only works for static pages (no JavaScript rendering). 1 MB max.
+
+```sh-session
+$ zurf fetch https://example.com               # markdown output
+$ zurf fetch https://example.com --html        # raw HTML output
+$ zurf fetch https://example.com -o page.md    # save full content to file
+$ zurf fetch https://example.com --proxies     # route through Browserbase proxies
+$ zurf fetch https://example.com --json        # JSON with content + metadata
+```
+
+| Flag | Description |
+|------|-------------|
+| `--html` | Output raw HTML instead of markdown |
+| `-o, --output` | Write full content to a file |
+| `--proxies` | Route through Browserbase proxies |
+| `--allow-redirects` | Follow HTTP redirects |
+| `--allow-insecure-ssl` | Disable TLS certificate verification |
+| `--json` | Print machine-readable JSON to stdout |
+
+### `zurf setup`
+
+Interactive wizard to configure API keys for all providers (Browserbase, Perplexity). Stores keys in global or local config. Re-run to update or add providers.
+
+```sh-session
+$ zurf setup                # interactive wizard
+$ zurf setup --global       # skip scope prompt, save to global config
+$ zurf setup --local        # skip scope prompt, save to project .zurf/config.json
+```
+
+### `zurf config which`
+
+Show where your API keys would be loaded from (nothing secret is printed). Shows resolution for both Browserbase and Perplexity.
+
+```sh-session
+$ zurf config which
+$ zurf config which --json
+```
+
+## Output format
+
+`zurf browse` and `zurf fetch` return **markdown** by default — smaller and more useful for LLM agents. Pass `--html` (or set `ZURF_HTML=true`) to get raw HTML instead.
+
+You can also set the default in `.zurf/config.json` or the global config:
+
+```json
+{ "format": "html" }
+```
+
+Format resolution (highest precedence first):
+
+1. `--html` flag
+2. `ZURF_HTML` environment variable (`true` or `1`)
+3. Local `.zurf/config.json` `format` field
+4. Global config `format` field
+5. Default: `markdown`
+
 ## Configuration
 
-API key resolution for `zurf search` and `zurf fetch` (highest precedence first):
+### Config file structure (v0.3.0+)
+
+```json
+{
+  "providers": {
+    "browserbase": {
+      "apiKey": "bb_...",
+      "projectId": "proj_..."
+    },
+    "perplexity": {
+      "apiKey": "pplx-..."
+    }
+  },
+  "format": "markdown"
+}
+```
+
+Old flat configs (v0.2.x) are auto-migrated when read — no manual action needed.
+
+### API key resolution
+
+Each provider resolves its key independently (highest precedence first):
+
+**Browserbase:**
+1. Environment variable `BROWSERBASE_API_KEY`
+2. Nearest `.zurf/config.json` → `providers.browserbase.apiKey`
+3. Global config → `providers.browserbase.apiKey`
 
-1. `--api-key` / `-k` on the command
-2. Environment variable `BROWSERBASE_API_KEY`
-3. Nearest `.zurf/config.json` when walking up from the current working directory
-4. Global file: `$XDG_CONFIG_HOME/zurf/config.json` if `XDG_CONFIG_HOME` is set, otherwise `~/.config/zurf/config.json` (on Windows, `%APPDATA%\zurf\config.json`)
+**Perplexity:**
+1. Environment variable `PERPLEXITY_API_KEY`
+2. Nearest `.zurf/config.json` → `providers.perplexity.apiKey`
+3. Global config → `providers.perplexity.apiKey`
 
-Save a key interactively or with `--api-key`:
+Save keys interactively:
 
 ```sh-session
-$ zurf init --global
-$ zurf init --local
+$ zurf setup
 ```
 
-For project-local storage, add `.zurf/` to `.gitignore` so the key is never committed. You can run `zurf init --local --gitignore` to append a `.zurf/` entry automatically.
+For project-local storage, add `.zurf/` to `.gitignore` so keys are never committed. `zurf setup --local` will offer to do this automatically.
 
-**Security note:** Keys in `config.json` are stored as plaintext with file mode `0o600`. For shared machines or stricter setups, prefer `BROWSERBASE_API_KEY` from your environment or a secrets manager instead of `init`.
+**Security note:** Keys in `config.json` are stored as plaintext with file mode `0o600`. For shared machines or stricter setups, prefer environment variables from a secrets manager.
 
-See where a key would be loaded from (nothing secret is printed): `zurf config which`.
+### Migration from v0.2.x
+
+- Config files auto-migrate from the old flat shape (`{ "apiKey": "..." }`) to the new nested shape. No manual changes needed.
+- `zurf init` has been replaced by `zurf setup`. The setup wizard supports multiple providers.
 
 ## Claude Code and agents
 
-Install `zurf` on your `PATH` and allow the agent to run shell commands. Use `--json` when you want a single JSON object on stdout, for example:
+Install `zurf` on your `PATH` and allow the agent to run shell commands. Use `--json` when you want structured output:
 
 ```sh-session
 $ zurf search "browserbase fetch api" --json
+$ zurf browse https://example.com --json
 $ zurf fetch https://example.com --json
+$ zurf ask "What is Browserbase?" --json
 ```
 
-## Installation
-
-```sh-session
-$ npm install -g @vibemastery/zurf
-$ zurf --help
-```
+Content is returned as markdown by default, which keeps token counts low. Pass `--html` if the agent needs the raw DOM.

package/dist/commands/ask/index.d.ts

@@ -0,0 +1,17 @@
+import { Command } from '@oclif/core';
+export default class Ask extends Command {
+    static args: {
+        question: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        citations: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        depth: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        domains: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        recency: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static summary: string;
+    run(): Promise<void>;
+}

package/dist/commands/ask/index.js

@@ -0,0 +1,102 @@
+import { Args, Command, Flags, ux } from '@oclif/core';
+import { cliError, errorMessage } from '../../lib/cli-errors.js';
+import { zurfJsonFlag } from '../../lib/flags.js';
+import { printJson } from '../../lib/json-output.js';
+import { createPerplexityClient, MissingPerplexityKeyError, } from '../../lib/perplexity-client.js';
+export default class Ask extends Command {
+    static args = {
+        question: Args.string({
+            description: 'The question to ask Perplexity',
+            required: true,
+        }),
+    };
+    static description = `Ask a question and get an AI-powered answer with web citations via Perplexity Sonar.
+Returns an answer with inline citations and a sources list. Use --depth deep for more thorough research.`;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> "What is Browserbase?"',
+        '<%= config.bin %> <%= command.id %> "latest tech news" --recency day',
+        '<%= config.bin %> <%= command.id %> "search reddit for best CLI tools" --domains reddit.com',
+        '<%= config.bin %> <%= command.id %> "explain quantum computing" --depth deep',
+        '<%= config.bin %> <%= command.id %> "What is Node.js?" --json',
+        '<%= config.bin %> <%= command.id %> "What is oclif?" --no-citations',
+    ];
+    static flags = {
+        citations: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Show sources list after the answer (use --no-citations to hide)',
+        }),
+        depth: Flags.string({
+            default: 'quick',
+            description: 'Search depth: quick (sonar) or deep (sonar-pro)',
+            options: ['quick', 'deep'],
+        }),
+        domains: Flags.string({
+            description: 'Restrict search to these domains (comma-separated)',
+        }),
+        json: zurfJsonFlag,
+        recency: Flags.string({
+            description: 'Filter sources by recency',
+            options: ['hour', 'day', 'week', 'month', 'year'],
+        }),
+    };
+    static summary = 'Ask a question via Perplexity Sonar';
+    async run() {
+        const { args, flags } = await this.parse(Ask);
+        const question = args.question.trim();
+        if (question.length === 0) {
+            cliError({ command: this, exitCode: 2, json: flags.json, message: 'Question must not be empty.' });
+        }
+        let client;
+        try {
+            ;
+            ({ client } = createPerplexityClient({ globalConfigDir: this.config.configDir }));
+        }
+        catch (error) {
+            if (error instanceof MissingPerplexityKeyError) {
+                cliError({ command: this, exitCode: 1, json: flags.json, message: error.message });
+            }
+            throw error;
+        }
+        const domains = flags.domains?.split(',').map((d) => d.trim()).filter(Boolean);
+        const doWork = async () => {
+            const result = await client.ask({
+                depth: flags.depth,
+                domains,
+                question,
+                recency: flags.recency,
+            });
+            if (flags.json) {
+                printJson({ answer: result.answer, citations: result.citations, model: result.model, query: question });
+                return;
+            }
+            this.log(result.answer);
+            if (flags.citations && result.citations.length > 0) {
+                this.log('');
+                this.log('Sources:');
+                for (const [i, url] of result.citations.entries()) {
+                    this.log(`[${i + 1}] ${url}`);
+                }
+            }
+        };
+        if (flags.json) {
+            try {
+                await doWork();
+            }
+            catch (error) {
+                cliError({ command: this, exitCode: 1, json: flags.json, message: errorMessage(error) });
+            }
+            return;
+        }
+        ux.action.start('Asking Perplexity');
+        try {
+            await doWork();
+        }
+        catch (error) {
+            cliError({ command: this, exitCode: 1, json: flags.json, message: errorMessage(error) });
+        }
+        finally {
+            ux.action.stop();
+        }
+    }
+}

package/dist/commands/browse/index.d.ts

@@ -0,0 +1,15 @@
+import { ZurfBrowserbaseCommand } from '../../lib/zurf-browserbase-command.js';
+export default class Browse extends ZurfBrowserbaseCommand {
+    static args: {
+        url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        html: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    run(): Promise<void>;
+}

package/dist/commands/browse/index.js

@@ -0,0 +1,109 @@
+import { Args, Flags } from '@oclif/core';
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { HUMAN_BODY_PREVIEW_CHARS, humanBrowseMetaLines, truncateNote, } from '../../lib/browse-output.js';
+import { withBrowserbaseSession } from '../../lib/browserbase-session.js';
+import { cliError, errorCode } from '../../lib/cli-errors.js';
+import { resolveFormat, resolveProjectId } from '../../lib/config.js';
+import { zurfBaseFlags } from '../../lib/flags.js';
+import { htmlToMarkdown } from '../../lib/html-to-markdown.js';
+import { printJson } from '../../lib/json-output.js';
+import { ZurfBrowserbaseCommand } from '../../lib/zurf-browserbase-command.js';
+export default class Browse extends ZurfBrowserbaseCommand {
+    static args = {
+        url: Args.string({
+            description: 'URL to browse',
+            required: true,
+        }),
+    };
+    static description = `Browse a URL in a cloud browser and return the rendered content as markdown (default) or raw HTML.
+Uses a real Chromium browser via Browserbase, so JavaScript-heavy pages are fully rendered.
+Requires authentication and a Project ID. Run \`zurf setup\` before first use.`;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> https://example.com',
+        '<%= config.bin %> <%= command.id %> https://example.com --html',
+        '<%= config.bin %> <%= command.id %> https://example.com --json',
+        '<%= config.bin %> <%= command.id %> https://example.com -o page.md',
+    ];
+    static flags = {
+        ...zurfBaseFlags,
+        output: Flags.string({
+            char: 'o',
+            description: 'Write rendered content to this file (full content); otherwise human mode prints a truncated preview to stdout',
+        }),
+    };
+    static summary = 'Browse a URL in a cloud browser and return rendered content as markdown';
+    async run() {
+        const { args, flags } = await this.parse(Browse);
+        const url = args.url.trim();
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            cliError({ command: this, exitCode: 2, json: flags.json, message: `Invalid URL: ${url}` });
+        }
+        if (!['http:', 'https:'].includes(parsed.protocol)) {
+            cliError({
+                command: this,
+                exitCode: 2,
+                json: flags.json,
+                message: `Only http and https URLs are supported: ${url}`,
+            });
+        }
+        if (!parsed.hostname) {
+            cliError({ command: this, exitCode: 2, json: flags.json, message: `Invalid URL: ${url}` });
+        }
+        await this.runWithBrowserbase(flags, `Browsing ${url}`, async (client) => {
+            const resolution = resolveProjectId({ globalConfigDir: this.config.configDir });
+            if (resolution.source === 'none') {
+                throw new Error('No Browserbase Project ID found. Set BROWSERBASE_PROJECT_ID, run `zurf setup` with --project-id, or add projectId to your .zurf/config.json.');
+            }
+            const { projectId } = resolution;
+            const result = await withBrowserbaseSession({
+                client,
+                projectId,
+                async work(page) {
+                    const response = await page.goto(url, { timeout: 30_000, waitUntil: 'networkidle' });
+                    const statusCode = response?.status() ?? null;
+                    const content = await page.content();
+                    return { content, statusCode };
+                },
+            });
+            const format = resolveFormat({ flagHtml: flags.html, globalConfigDir: this.config.configDir });
+            const content = format === 'markdown' ? await htmlToMarkdown(result.content) : result.content;
+            if (flags.json) {
+                const payload = { content, format, statusCode: result.statusCode, url };
+                printJson(payload);
+                return;
+            }
+            this.logToStderr(humanBrowseMetaLines({ statusCode: result.statusCode, url }).join('\n'));
+            this.logToStderr('');
+            if (flags.output) {
+                try {
+                    await fs.writeFile(flags.output, content, 'utf8');
+                }
+                catch (error) {
+                    if (errorCode(error) === 'ENOENT') {
+                        cliError({
+                            command: this,
+                            exitCode: 1,
+                            json: flags.json,
+                            message: `Directory does not exist for output file: ${path.dirname(path.resolve(flags.output))}`,
+                        });
+                    }
+                    throw error;
+                }
+                this.logToStderr(`Wrote rendered content to ${flags.output}`);
+                return;
+            }
+            if (content.length <= HUMAN_BODY_PREVIEW_CHARS) {
+                this.log(content);
+                return;
+            }
+            this.log(content.slice(0, HUMAN_BODY_PREVIEW_CHARS));
+            this.log('');
+            this.logToStderr(truncateNote(content.length));
+        });
+    }
+}

package/dist/commands/config/which.d.ts

@@ -3,6 +3,7 @@ export default class ConfigWhich extends Command {
     static description: string;
     static examples: string[];
     static flags: {
+        html: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static summary: string;

package/dist/commands/config/which.js

@@ -1,61 +1,68 @@
 import { Command } from '@oclif/core';
-import { globalConfigFilePath, resolveApiKey } from '../../lib/config.js';
+import { globalConfigFilePath, resolveApiKey, resolvePerplexityApiKey } from '../../lib/config.js';
 import { zurfBaseFlags } from '../../lib/flags.js';
 import { printJson } from '../../lib/json-output.js';
+function resolvedSource(resolved) {
+    switch (resolved.source) {
+        case 'env': {
+            return { source: 'env' };
+        }
+        case 'global':
+        case 'local': {
+            return { path: resolved.path, source: resolved.source };
+        }
+        default: {
+            return { source: 'none' };
+        }
+    }
+}
+function humanSourceLine(label, resolved, envVarName) {
+    switch (resolved.source) {
+        case 'env': {
+            return `${label}: environment variable ${envVarName}`;
+        }
+        case 'global': {
+            return `${label}: global file ${resolved.path}`;
+        }
+        case 'local': {
+            return `${label}: local file ${resolved.path}`;
+        }
+        default: {
+            return `${label}: not configured`;
+        }
+    }
+}
 export default class ConfigWhich extends Command {
-    static description = `Show where the Browserbase API key would be loaded from (no secret printed).
-Resolution order: BROWSERBASE_API_KEY, then project .zurf/config.json (walk-up), then global config in the CLI config directory.`;
+    static description = `Show where API keys would be loaded from (no secrets printed).
+Resolution order: env var → project .zurf/config.json (walk-up) → global config.`;
     static examples = ['<%= config.bin %> config which', '<%= config.bin %> config which --json'];
     static flags = {
         ...zurfBaseFlags,
     };
-    static summary = 'Show where the API key is loaded from';
+    static summary = 'Show where API keys are loaded from';
     async run() {
         const { flags } = await this.parse(ConfigWhich);
-        const resolved = resolveApiKey({ globalConfigDir: this.config.configDir });
+        const bbResolved = resolveApiKey({ globalConfigDir: this.config.configDir });
+        const pplxResolved = resolvePerplexityApiKey({ globalConfigDir: this.config.configDir });
         if (flags.json) {
-            switch (resolved.source) {
-                case 'env': {
-                    printJson({ envVar: 'BROWSERBASE_API_KEY', source: 'env' });
-                    break;
-                }
-                case 'global': {
-                    printJson({ path: resolved.path, source: 'global' });
-                    break;
-                }
-                case 'local': {
-                    printJson({ path: resolved.path, source: 'local' });
-                    break;
-                }
-                case 'none': {
-                    printJson({
-                        globalConfigPath: globalConfigFilePath(this.config.configDir),
-                        hint: `Run \`${this.config.bin} init --global\` or \`${this.config.bin} init --local\`, or set BROWSERBASE_API_KEY.`,
-                        source: 'none',
-                    });
-                    this.exit(1);
-                    break;
-                }
+            const payload = {
+                browserbase: resolvedSource(bbResolved),
+                perplexity: resolvedSource(pplxResolved),
+            };
+            if (bbResolved.source === 'none' && pplxResolved.source === 'none') {
+                payload.globalConfigPath = globalConfigFilePath(this.config.configDir);
+                payload.hint = `Run \`${this.config.bin} setup\` or set BROWSERBASE_API_KEY / PERPLEXITY_API_KEY.`;
+            }
+            printJson(payload);
+            if (bbResolved.source === 'none' && pplxResolved.source === 'none') {
+                this.exit(1);
             }
             return;
         }
-        switch (resolved.source) {
-            case 'env': {
-                this.log('API key source: environment variable BROWSERBASE_API_KEY');
-                break;
-            }
-            case 'global': {
-                this.log(`API key source: global file ${resolved.path}`);
-                break;
-            }
-            case 'local': {
-                this.log(`API key source: local file ${resolved.path}`);
-                break;
-            }
-            case 'none': {
-                this.error(`No API key configured. Set BROWSERBASE_API_KEY or run \`${this.config.bin} init --global\` / \`--local\`.`);
-                break;
-            }
+        this.log(humanSourceLine('Browserbase API key', bbResolved, 'BROWSERBASE_API_KEY'));
+        this.log(humanSourceLine('Perplexity API key', pplxResolved, 'PERPLEXITY_API_KEY'));
+        if (bbResolved.source === 'none' && pplxResolved.source === 'none') {
+            this.error(`No API keys configured. Run \`${this.config.bin} setup\` or set environment variables.`);
         }
     }
 }

package/dist/commands/fetch/index.d.ts

@@ -10,6 +10,7 @@ export default class Fetch extends ZurfBrowserbaseCommand {
         'allow-redirects': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         output: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         proxies: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        html: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static summary: string;