@vibemastery/zurf 0.2.2 → 0.2.3

package/README.md

@@ -1,23 +1,124 @@
 zurf
 =================
 
-A lightweight CLI for searching and fetching web pages, powered by Browserbase.
+A lightweight CLI for searching, browsing, and fetching web pages, powered by Browserbase.
 
 
 [![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 init --global          # save your Browserbase API key
+$ zurf --help
+```
+
+## Commands
+
+### `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 init`
+
+Save your Browserbase API key and optional Project ID to a config file.
+
+```sh-session
+$ zurf init --global                              # save to global config
+$ zurf init --local                               # save to project .zurf/config.json
+$ zurf init --local --gitignore                   # also append .zurf/ to .gitignore
+$ zurf init --global --project-id <project-id>    # save project ID too
+```
+
+### `zurf config which`
+
+Show where your API key and Project ID would be loaded from (nothing secret is printed).
+
+```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):
+API key resolution (highest precedence first):
 
-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`)
+1. Environment variable `BROWSERBASE_API_KEY`
+2. Nearest `.zurf/config.json` when walking up from the current working directory
+3. Global config: `$XDG_CONFIG_HOME/zurf/config.json` (or `~/.config/zurf/config.json`)
 
-Save a key interactively or with `--api-key`:
+Save a key interactively:
 
 ```sh-session
 $ zurf init --global
@@ -28,20 +129,14 @@ For project-local storage, add `.zurf/` to `.gitignore` so the key is never comm
 
 **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`.
 
-See where a key would be loaded from (nothing secret is printed): `zurf config which`.
-
 ## 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
 ```
 
-## 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/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 init --global\` 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 init --global` 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/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;

package/dist/commands/fetch/index.js

@@ -1,9 +1,11 @@
 import { Args, Flags } from '@oclif/core';
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
-import { cliError } from '../../lib/cli-errors.js';
+import { cliError, errorCode } from '../../lib/cli-errors.js';
+import { resolveFormat } from '../../lib/config.js';
 import { buildFetchJsonPayload, HUMAN_BODY_PREVIEW_CHARS, humanFetchMetaLines, truncateNote, } from '../../lib/fetch-output.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 Fetch extends ZurfBrowserbaseCommand {
@@ -13,12 +15,13 @@ export default class Fetch extends ZurfBrowserbaseCommand {
             required: true,
         }),
     };
-    static description = `Fetch a URL via Browserbase (no browser session; static HTML, 1 MB max).
+    static description = `Fetch a URL via Browserbase and return content as markdown (default) or raw HTML (no browser session; static HTML, 1 MB max).
 Requires authentication. Run \`zurf init --global\` or use a project key 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.html --proxies',
+        '<%= config.bin %> <%= command.id %> https://example.com -o page.md --proxies',
     ];
     static flags = {
         ...zurfBaseFlags,
@@ -39,7 +42,7 @@ Requires authentication. Run \`zurf init --global\` or use a project key before
             description: 'Route through Browserbase proxies (helps with some blocked sites)',
         }),
     };
-    static summary = 'Fetch a URL via Browserbase';
+    static summary = 'Fetch a URL via Browserbase and return content as markdown';
     async run() {
         const { args, flags } = await this.parse(Fetch);
         const url = args.url.trim();
@@ -68,24 +71,21 @@ Requires authentication. Run \`zurf init --global\` or use a project key before
                 proxies: flags.proxies,
                 url,
             });
+            const format = resolveFormat({ flagHtml: flags.html, globalConfigDir: this.config.configDir });
+            const content = format === 'markdown' ? await htmlToMarkdown(response.content) : response.content;
+            const converted = { ...response, content };
             if (flags.json) {
-                printJson(buildFetchJsonPayload(response));
+                printJson(buildFetchJsonPayload(converted, format));
                 return;
             }
             this.logToStderr(humanFetchMetaLines(response).join('\n'));
             this.logToStderr('');
             if (flags.output) {
                 try {
-                    await fs.writeFile(flags.output, response.content, 'utf8');
+                    await fs.writeFile(flags.output, content, 'utf8');
                 }
                 catch (error) {
-                    const code = error !== null &&
-                        typeof error === 'object' &&
-                        'code' in error &&
-                        typeof error.code === 'string'
-                        ? error.code
-                        : undefined;
-                    if (code === 'ENOENT') {
+                    if (errorCode(error) === 'ENOENT') {
                         cliError({
                             command: this,
                             exitCode: 1,
@@ -95,10 +95,9 @@ Requires authentication. Run \`zurf init --global\` or use a project key before
                     }
                     throw error;
                 }
-                this.logToStderr(`Wrote body to ${flags.output}`);
+                this.logToStderr(`Wrote content to ${flags.output}`);
                 return;
             }
-            const { content } = response;
             if (content.length <= HUMAN_BODY_PREVIEW_CHARS) {
                 this.log(content);
                 return;

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

@@ -7,9 +7,12 @@ export default class Init extends Command {
         gitignore: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         local: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'project-id': 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>;
     private readApiKeyForInit;
+    private readProjectIdForInit;
 }

package/dist/commands/init/index.js

@@ -1,17 +1,18 @@
 import { Command, Flags } from '@oclif/core';
 import * as fs from 'node:fs/promises';
 import { cliError, errorMessage } from '../../lib/cli-errors.js';
-import { globalConfigFilePath, localConfigPathForCwd, writeApiKeyConfig } from '../../lib/config.js';
+import { globalConfigFilePath, localConfigPathForCwd, writeConfig } from '../../lib/config.js';
 import { zurfBaseFlags } from '../../lib/flags.js';
 import { dotGitignoreMentionsZurf, ensureZurfGitignoreEntry, gitignorePathForCwd, } from '../../lib/gitignore-zurf.js';
 import { promptLine, readStdinIfPiped } from '../../lib/init-input.js';
 import { printJson } from '../../lib/json-output.js';
 export default class Init extends Command {
-    static description = `Save your Browserbase API key to global or project config.
+    static description = `Save your Browserbase API key and optional Project ID to global or project config.
 Global path follows oclif config (same as \`zurf config which\`).`;
     static examples = [
         '<%= config.bin %> <%= command.id %> --global',
         '<%= config.bin %> <%= command.id %> --local',
+        '<%= config.bin %> <%= command.id %> --global --api-key KEY --project-id PROJ_ID',
         'printenv BROWSERBASE_API_KEY | <%= config.bin %> <%= command.id %> --global',
     ];
     static flags = {
@@ -30,16 +31,23 @@ Global path follows oclif config (same as \`zurf config which\`).`;
             description: 'Store API key in ./.zurf/config.json for this directory',
             exactlyOne: ['global', 'local'],
         }),
+        'project-id': Flags.string({
+            description: 'Browserbase Project ID (optional; needed for browse, screenshot, pdf commands)',
+        }),
     };
-    static summary = 'Configure Browserbase API key storage';
+    static summary = 'Configure Browserbase API key and Project ID storage';
     async run() {
         const { flags } = await this.parse(Init);
         const apiKey = await this.readApiKeyForInit(flags);
         const targetPath = flags.global
             ? globalConfigFilePath(this.config.configDir)
             : localConfigPathForCwd();
+        const projectId = await this.readProjectIdForInit(flags);
+        const configUpdate = { apiKey: apiKey.trim() };
+        if (projectId)
+            configUpdate.projectId = projectId;
         try {
-            await writeApiKeyConfig(targetPath, apiKey);
+            await writeConfig(targetPath, configUpdate);
         }
         catch (error) {
             cliError({ command: this, exitCode: 1, json: flags.json, message: errorMessage(error) });
@@ -53,10 +61,16 @@ Global path follows oclif config (same as \`zurf config which\`).`;
             }
         }
         if (flags.json) {
-            printJson({ ok: true, path: targetPath, scope: flags.global ? 'global' : 'local' });
+            const payload = { ok: true, path: targetPath, scope: flags.global ? 'global' : 'local' };
+            if (projectId)
+                payload.projectId = true;
+            printJson(payload);
         }
         else {
             this.log(`Saved API key to ${targetPath}`);
+            if (projectId) {
+                this.log(`Saved Project ID to ${targetPath}`);
+            }
             if (flags.local) {
                 let showTip = true;
                 try {
@@ -92,4 +106,11 @@ Global path follows oclif config (same as \`zurf config which\`).`;
         }
         return apiKey;
     }
+    async readProjectIdForInit(flags) {
+        let projectId = flags['project-id']?.trim();
+        if (!projectId && !flags.json && process.stdin.isTTY) {
+            projectId = await promptLine('Browserbase Project ID (optional, press Enter to skip): ');
+        }
+        return projectId || undefined;
+    }
 }

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

@@ -7,6 +7,7 @@ export default class Search extends ZurfBrowserbaseCommand {
     static examples: string[];
     static flags: {
         'num-results': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        html: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static summary: string;

package/dist/lib/browse-output.d.ts

@@ -0,0 +1,12 @@
+export interface BrowseJsonPayload {
+    content: string;
+    format: 'html' | 'markdown';
+    statusCode: null | number;
+    url: string;
+}
+export declare function humanBrowseMetaLines(options: {
+    statusCode: null | number;
+    url: string;
+}): string[];
+export declare const HUMAN_BODY_PREVIEW_CHARS = 8000;
+export declare function truncateNote(totalChars: number): string;

package/dist/lib/browse-output.js

@@ -0,0 +1,10 @@
+export function humanBrowseMetaLines(options) {
+    return [
+        `url: ${options.url}`,
+        `statusCode: ${options.statusCode ?? 'unknown'}`,
+    ];
+}
+export const HUMAN_BODY_PREVIEW_CHARS = 8000;
+export function truncateNote(totalChars) {
+    return `… truncated (${totalChars} chars). Use --output FILE to save the full content.`;
+}

package/dist/lib/browserbase-session.d.ts

@@ -0,0 +1,7 @@
+import type { Browserbase } from '@browserbasehq/sdk';
+import type { Page } from 'playwright-core';
+export declare function withBrowserbaseSession<T>(options: {
+    client: Browserbase;
+    projectId: string;
+    work: (page: Page) => Promise<T>;
+}): Promise<T>;

package/dist/lib/browserbase-session.js

@@ -0,0 +1,39 @@
+export async function withBrowserbaseSession(options) {
+    const { chromium } = await import('playwright-core');
+    const { client, projectId, work } = options;
+    const session = await client.sessions.create({ projectId });
+    const browser = await chromium.connectOverCDP(session.connectUrl);
+    let cleanedUp = false;
+    const cleanup = async () => {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        try {
+            const pages = browser.contexts()[0]?.pages() ?? [];
+            await Promise.all(pages.map((p) => p.close().catch(() => { })));
+            await browser.close().catch(() => { });
+        }
+        finally {
+            await client.sessions.update(session.id, { status: 'REQUEST_RELEASE' }).catch(() => { });
+        }
+    };
+    const onSignal = () => {
+        // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+        cleanup().then(() => process.exit(1), () => process.exit(1));
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    try {
+        const defaultContext = browser.contexts()[0];
+        if (!defaultContext) {
+            throw new Error('No browser context available from Browserbase session');
+        }
+        const page = defaultContext.pages()[0] ?? (await defaultContext.newPage());
+        return await work(page);
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        await cleanup();
+    }
+}

package/dist/lib/cli-errors.d.ts

@@ -14,6 +14,7 @@ export declare class CliJsonExitContractError extends Error {
     constructor();
 }
 export declare function errorMessage(err: unknown): string;
+export declare function errorCode(err: unknown): string | undefined;
 export declare function errorStatus(err: unknown): number | undefined;
 /** Print JSON or human error and exit; does not return. */
 export declare function cliError(options: CliErrorOptions): never;

package/dist/lib/cli-errors.js

@@ -15,6 +15,15 @@ export function errorMessage(err) {
     }
     return String(err);
 }
+export function errorCode(err) {
+    if (err !== null &&
+        typeof err === 'object' &&
+        'code' in err &&
+        typeof err.code === 'string') {
+        return err.code;
+    }
+    return undefined;
+}
 export function errorStatus(err) {
     if (err !== null &&
         typeof err === 'object' &&

package/dist/lib/config.d.ts

@@ -20,15 +20,41 @@ export type ActiveApiKey = Extract<ResolvedApiKey, {
 }>;
 export interface ConfigFileShape {
     apiKey?: string;
+    format?: 'html' | 'markdown';
+    projectId?: string;
 }
+export type ResolvedProjectId = {
+    path: string;
+    projectId: string;
+    source: 'global';
+} | {
+    path: string;
+    projectId: string;
+    source: 'local';
+} | {
+    projectId: string;
+    source: 'env';
+} | {
+    source: 'none';
+};
 /**
  * Path to global `config.json` under oclif's `this.config.configDir` (same rules as @oclif/core `Config.dir('config')` for `dirname` zurf).
  */
 export declare function globalConfigFilePath(oclifConfigDir: string): string;
 export declare function localConfigPathForCwd(cwd?: string): string;
 export declare function findLocalConfigPath(startDir?: string): string | undefined;
+export declare function resolveFormat(options: {
+    cwd?: string;
+    flagHtml: boolean;
+    globalConfigDir: string;
+}): 'html' | 'markdown';
 export declare function resolveApiKey(options: {
     cwd?: string;
     globalConfigDir: string;
 }): ResolvedApiKey;
+export declare function resolveProjectId(options: {
+    cwd?: string;
+    globalConfigDir: string;
+}): ResolvedProjectId;
 export declare function writeApiKeyConfig(targetPath: string, apiKey: string): Promise<void>;
+export declare function writeConfig(targetPath: string, fields: Partial<ConfigFileShape>): Promise<void>;

package/dist/lib/config.js

@@ -26,17 +26,57 @@ export function findLocalConfigPath(startDir = process.cwd()) {
     }
     return undefined;
 }
-function readApiKeyFromFile(filePath) {
+function readConfigFile(filePath) {
     try {
         const raw = fs.readFileSync(filePath, 'utf8');
-        const parsed = JSON.parse(raw);
-        const key = typeof parsed.apiKey === 'string' ? parsed.apiKey.trim() : '';
-        return key.length > 0 ? key : undefined;
+        return JSON.parse(raw);
     }
     catch {
         return undefined;
     }
 }
+function readApiKeyFromFile(filePath) {
+    const parsed = readConfigFile(filePath);
+    if (!parsed)
+        return undefined;
+    const key = typeof parsed.apiKey === 'string' ? parsed.apiKey.trim() : '';
+    return key.length > 0 ? key : undefined;
+}
+function readProjectIdFromFile(filePath) {
+    const parsed = readConfigFile(filePath);
+    if (!parsed)
+        return undefined;
+    const id = typeof parsed.projectId === 'string' ? parsed.projectId.trim() : '';
+    return id.length > 0 ? id : undefined;
+}
+function readFormatFromFile(filePath) {
+    const parsed = readConfigFile(filePath);
+    if (!parsed)
+        return undefined;
+    const fmt = parsed.format;
+    if (fmt === 'html' || fmt === 'markdown')
+        return fmt;
+    return undefined;
+}
+export function resolveFormat(options) {
+    if (options.flagHtml)
+        return 'html';
+    const envVal = process.env.ZURF_HTML?.trim().toLowerCase();
+    if (envVal === 'true' || envVal === '1')
+        return 'html';
+    const cwd = options.cwd ?? process.cwd();
+    const localPath = findLocalConfigPath(cwd);
+    if (localPath) {
+        const fmt = readFormatFromFile(localPath);
+        if (fmt)
+            return fmt;
+    }
+    const gPath = globalConfigFilePath(options.globalConfigDir);
+    const globalFmt = readFormatFromFile(gPath);
+    if (globalFmt)
+        return globalFmt;
+    return 'markdown';
+}
 export function resolveApiKey(options) {
     const cwd = options.cwd ?? process.cwd();
     const envKey = process.env.BROWSERBASE_API_KEY?.trim();
@@ -57,10 +97,41 @@ export function resolveApiKey(options) {
     }
     return { source: 'none' };
 }
+export function resolveProjectId(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const envId = process.env.BROWSERBASE_PROJECT_ID?.trim();
+    if (envId) {
+        return { projectId: envId, source: 'env' };
+    }
+    const localPath = findLocalConfigPath(cwd);
+    if (localPath) {
+        const id = readProjectIdFromFile(localPath);
+        if (id) {
+            return { path: localPath, projectId: id, source: 'local' };
+        }
+    }
+    const gPath = globalConfigFilePath(options.globalConfigDir);
+    const globalId = readProjectIdFromFile(gPath);
+    if (globalId) {
+        return { path: gPath, projectId: globalId, source: 'global' };
+    }
+    return { source: 'none' };
+}
 export async function writeApiKeyConfig(targetPath, apiKey) {
+    await writeConfig(targetPath, { apiKey: apiKey.trim() });
+}
+export async function writeConfig(targetPath, fields) {
     const dir = path.dirname(targetPath);
     await fs.promises.mkdir(dir, { recursive: true });
-    const payload = { apiKey: apiKey.trim() };
-    const body = `${JSON.stringify(payload, null, 2)}\n`;
+    let existing = {};
+    try {
+        const raw = await fs.promises.readFile(targetPath, 'utf8');
+        existing = JSON.parse(raw);
+    }
+    catch {
+        // file doesn't exist yet — start fresh
+    }
+    const merged = { ...existing, ...fields };
+    const body = `${JSON.stringify(merged, null, 2)}\n`;
     await fs.promises.writeFile(targetPath, body, { encoding: 'utf8', mode: 0o600 });
 }

package/dist/lib/fetch-output.d.ts

@@ -6,10 +6,11 @@ export type FetchResponseForDisplay = {
     id: string;
     statusCode: number;
 };
-export declare function buildFetchJsonPayload(response: FetchResponseForDisplay): {
+export declare function buildFetchJsonPayload(response: FetchResponseForDisplay, format: 'html' | 'markdown'): {
     content: string;
     contentType: string;
     encoding: string;
+    format: 'html' | 'markdown';
     headers: Record<string, string>;
     id: string;
     statusCode: number;

package/dist/lib/fetch-output.js

@@ -1,8 +1,9 @@
-export function buildFetchJsonPayload(response) {
+export function buildFetchJsonPayload(response, format) {
     return {
         content: response.content,
         contentType: response.contentType,
         encoding: response.encoding,
+        format,
         headers: response.headers,
         id: response.id,
         statusCode: response.statusCode,
@@ -19,5 +20,5 @@ export function humanFetchMetaLines(response) {
 /** ~8k chars keeps terminal scrollback usable while showing most HTML pages in preview. */
 export const HUMAN_BODY_PREVIEW_CHARS = 8000;
 export function truncateNote(totalChars) {
-    return `… truncated (${totalChars} chars). Use --output FILE to save the full body (within the 1 MB Fetch limit).`;
+    return `… truncated (${totalChars} chars). Use --output FILE to save the full content (within the 1 MB Fetch limit).`;
 }

package/dist/lib/flags.d.ts

@@ -1,6 +1,9 @@
 /** Machine-readable output; kept separate from oclif `enableJsonFlag` so error payloads match zurf's stdout JSON contract. */
 export declare const zurfJsonFlag: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+/** Output raw HTML instead of the default markdown conversion. */
+export declare const zurfHtmlFlag: import("@oclif/core/interfaces").BooleanFlag<boolean>;
 /** Shared flags for commands that support JSON output (no `--api-key` — use BROWSERBASE_API_KEY or config files). */
 export declare const zurfBaseFlags: {
+    readonly html: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     readonly json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
 };

package/dist/lib/flags.js

@@ -4,7 +4,14 @@ export const zurfJsonFlag = Flags.boolean({
     description: 'Print machine-readable JSON to stdout',
     env: 'ZURF_JSON',
 });
+/** Output raw HTML instead of the default markdown conversion. */
+export const zurfHtmlFlag = Flags.boolean({
+    default: false,
+    description: 'Output raw HTML instead of markdown',
+    env: 'ZURF_HTML',
+});
 /** Shared flags for commands that support JSON output (no `--api-key` — use BROWSERBASE_API_KEY or config files). */
 export const zurfBaseFlags = {
+    html: zurfHtmlFlag,
     json: zurfJsonFlag,
 };

package/dist/lib/html-to-markdown.d.ts

@@ -0,0 +1 @@
+export declare function htmlToMarkdown(html: string): Promise<string>;

package/dist/lib/html-to-markdown.js

@@ -0,0 +1,21 @@
+let cached;
+async function getService() {
+    if (cached)
+        return cached;
+    const { default: Turndown } = await import('turndown');
+    const service = new Turndown({
+        codeBlockStyle: 'fenced',
+        headingStyle: 'atx',
+    });
+    service.remove(['script', 'style', 'iframe', 'noscript']);
+    service.addRule('remove-svg', {
+        filter: (node) => node.nodeName.toLowerCase() === 'svg',
+        replacement: () => '',
+    });
+    cached = service;
+    return service;
+}
+export async function htmlToMarkdown(html) {
+    const service = await getService();
+    return service.turndown(html);
+}

package/oclif.manifest.json

@@ -1,115 +1,120 @@
 {
   "commands": {
-    "config:which": {
+    "browse": {
       "aliases": [],
-      "args": {},
-      "description": "Show where the Browserbase API key would be loaded from (no secret printed).\nResolution order: BROWSERBASE_API_KEY, then project .zurf/config.json (walk-up), then global config in the CLI config directory.",
+      "args": {
+        "url": {
+          "description": "URL to browse",
+          "name": "url",
+          "required": true
+        }
+      },
+      "description": "Browse a URL in a cloud browser and return the rendered content as markdown (default) or raw HTML.\nUses a real Chromium browser via Browserbase, so JavaScript-heavy pages are fully rendered.\nRequires authentication and a Project ID. Run `zurf init --global` before first use.",
       "examples": [
-        "<%= config.bin %> config which",
-        "<%= config.bin %> config which --json"
+        "<%= 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"
       ],
       "flags": {
+        "html": {
+          "description": "Output raw HTML instead of markdown",
+          "env": "ZURF_HTML",
+          "name": "html",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "json": {
           "description": "Print machine-readable JSON to stdout",
           "env": "ZURF_JSON",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
+        },
+        "output": {
+          "char": "o",
+          "description": "Write rendered content to this file (full content); otherwise human mode prints a truncated preview to stdout",
+          "name": "output",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "config:which",
+      "id": "browse",
       "pluginAlias": "@vibemastery/zurf",
       "pluginName": "@vibemastery/zurf",
       "pluginType": "core",
       "strict": true,
-      "summary": "Show where the API key is loaded from",
-      "enableJsonFlag": false,
+      "summary": "Browse a URL in a cloud browser and return rendered content as markdown",
       "isESM": true,
       "relativePath": [
         "dist",
         "commands",
-        "config",
-        "which.js"
+        "browse",
+        "index.js"
       ]
     },
-    "fetch": {
+    "config:which": {
       "aliases": [],
-      "args": {
-        "url": {
-          "description": "URL to fetch",
-          "name": "url",
-          "required": true
-        }
-      },
-      "description": "Fetch a URL via Browserbase (no browser session; static HTML, 1 MB max).\nRequires authentication. Run `zurf init --global` or use a project key before first use.",
+      "args": {},
+      "description": "Show where the Browserbase API key would be loaded from (no secret printed).\nResolution order: BROWSERBASE_API_KEY, then project .zurf/config.json (walk-up), then global config in the CLI config directory.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> https://example.com",
-        "<%= config.bin %> <%= command.id %> https://example.com --json",
-        "<%= config.bin %> <%= command.id %> https://example.com -o page.html --proxies"
+        "<%= config.bin %> config which",
+        "<%= config.bin %> config which --json"
       ],
       "flags": {
+        "html": {
+          "description": "Output raw HTML instead of markdown",
+          "env": "ZURF_HTML",
+          "name": "html",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "json": {
           "description": "Print machine-readable JSON to stdout",
           "env": "ZURF_JSON",
           "name": "json",
           "allowNo": false,
           "type": "boolean"
-        },
-        "allow-insecure-ssl": {
-          "description": "Disable TLS certificate verification (use only if you trust the target)",
-          "name": "allow-insecure-ssl",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "allow-redirects": {
-          "description": "Follow HTTP redirects",
-          "name": "allow-redirects",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "output": {
-          "char": "o",
-          "description": "Write response body to this file (full content); otherwise human mode prints a truncated preview to stdout",
-          "name": "output",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "proxies": {
-          "description": "Route through Browserbase proxies (helps with some blocked sites)",
-          "name": "proxies",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "fetch",
+      "id": "config:which",
       "pluginAlias": "@vibemastery/zurf",
       "pluginName": "@vibemastery/zurf",
       "pluginType": "core",
       "strict": true,
-      "summary": "Fetch a URL via Browserbase",
+      "summary": "Show where the API key is loaded from",
+      "enableJsonFlag": false,
       "isESM": true,
       "relativePath": [
         "dist",
         "commands",
-        "fetch",
-        "index.js"
+        "config",
+        "which.js"
       ]
     },
     "init": {
       "aliases": [],
       "args": {},
-      "description": "Save your Browserbase API key to global or project config.\nGlobal path follows oclif config (same as `zurf config which`).",
+      "description": "Save your Browserbase API key and optional Project ID to global or project config.\nGlobal path follows oclif config (same as `zurf config which`).",
       "examples": [
         "<%= config.bin %> <%= command.id %> --global",
         "<%= config.bin %> <%= command.id %> --local",
+        "<%= config.bin %> <%= command.id %> --global --api-key KEY --project-id PROJ_ID",
         "printenv BROWSERBASE_API_KEY | <%= config.bin %> <%= command.id %> --global"
       ],
       "flags": {
+        "html": {
+          "description": "Output raw HTML instead of markdown",
+          "env": "ZURF_HTML",
+          "name": "html",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "json": {
           "description": "Print machine-readable JSON to stdout",
           "env": "ZURF_JSON",
@@ -141,6 +146,13 @@
           "name": "local",
           "allowNo": false,
           "type": "boolean"
+        },
+        "project-id": {
+          "description": "Browserbase Project ID (optional; needed for browse, screenshot, pdf commands)",
+          "name": "project-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -150,7 +162,7 @@
       "pluginName": "@vibemastery/zurf",
       "pluginType": "core",
       "strict": true,
-      "summary": "Configure Browserbase API key storage",
+      "summary": "Configure Browserbase API key and Project ID storage",
       "enableJsonFlag": false,
       "isESM": true,
       "relativePath": [
@@ -160,6 +172,80 @@
         "index.js"
       ]
     },
+    "fetch": {
+      "aliases": [],
+      "args": {
+        "url": {
+          "description": "URL to fetch",
+          "name": "url",
+          "required": true
+        }
+      },
+      "description": "Fetch a URL via Browserbase and return content as markdown (default) or raw HTML (no browser session; static HTML, 1 MB max).\nRequires authentication. Run `zurf init --global` or use a project key before first use.",
+      "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 --proxies"
+      ],
+      "flags": {
+        "html": {
+          "description": "Output raw HTML instead of markdown",
+          "env": "ZURF_HTML",
+          "name": "html",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "json": {
+          "description": "Print machine-readable JSON to stdout",
+          "env": "ZURF_JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "allow-insecure-ssl": {
+          "description": "Disable TLS certificate verification (use only if you trust the target)",
+          "name": "allow-insecure-ssl",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "allow-redirects": {
+          "description": "Follow HTTP redirects",
+          "name": "allow-redirects",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "output": {
+          "char": "o",
+          "description": "Write response body to this file (full content); otherwise human mode prints a truncated preview to stdout",
+          "name": "output",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "proxies": {
+          "description": "Route through Browserbase proxies (helps with some blocked sites)",
+          "name": "proxies",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "fetch",
+      "pluginAlias": "@vibemastery/zurf",
+      "pluginName": "@vibemastery/zurf",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Fetch a URL via Browserbase and return content as markdown",
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "fetch",
+        "index.js"
+      ]
+    },
     "search": {
       "aliases": [],
       "args": {
@@ -175,6 +261,13 @@
         "<%= config.bin %> <%= command.id %> \"laravel inertia\" --num-results 5 --json"
       ],
       "flags": {
+        "html": {
+          "description": "Output raw HTML instead of markdown",
+          "env": "ZURF_HTML",
+          "name": "html",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "json": {
           "description": "Print machine-readable JSON to stdout",
           "env": "ZURF_JSON",
@@ -209,5 +302,5 @@
       ]
     }
   },
-  "version": "0.2.2"
+  "version": "0.2.3"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vibemastery/zurf",
   "description": "A lightweight CLI for searching and fetching web pages, powered by Browserbase.",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "author": "Luis Güette",
   "bin": {
     "zurf": "./bin/run.js"
@@ -14,7 +14,9 @@
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-not-found": "^3.2.77",
     "@oclif/plugin-plugins": "^5",
-    "@oclif/plugin-warn-if-update-available": "^3.1.57"
+    "@oclif/plugin-warn-if-update-available": "^3.1.57",
+    "playwright-core": "^1.58.2",
+    "turndown": "^7.2.2"
   },
   "devDependencies": {
     "@eslint/compat": "^1",
@@ -23,6 +25,7 @@
     "@types/chai": "^4",
     "@types/mocha": "^10",
     "@types/node": "^18",
+    "@types/turndown": "^5.0.6",
     "chai": "^4",
     "eslint": "^9",
     "eslint-config-oclif": "^6",