@vibemastery/zurf 0.1.0 → 0.2.3

package/README.md

@@ -1,541 +1,142 @@
 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/zurf.svg)](https://npmjs.org/package/zurf)
-[![Downloads/week](https://img.shields.io/npm/dw/zurf.svg)](https://npmjs.org/package/zurf)
+[![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)
 
-## Configuration
-
-API key resolution for `zurf search` and `zurf fetch` (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`)
-
-Save a key interactively or with `--api-key`:
+## Installation
 
-```sh-session
-$ zurf init --global
-$ zurf init --local
-```
-
-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.
-
-**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:
-
-```sh-session
-$ zurf search "browserbase fetch api" --json
-$ zurf fetch https://example.com --json
-```
-
-<!-- toc -->
-* [Usage](#usage)
-* [Commands](#commands)
-<!-- tocstop -->
-# Usage
-<!-- usage -->
 ```sh-session
 $ npm install -g @vibemastery/zurf
-$ zurf COMMAND
-running command...
-$ zurf (--version)
-@vibemastery/zurf/0.1.0 darwin-arm64 node-v22.22.2
-$ zurf --help [COMMAND]
-USAGE
-  $ zurf COMMAND
-...
-```
-<!-- usagestop -->
-# Commands
-<!-- commands -->
-* [`zurf autocomplete [SHELL]`](#zurf-autocomplete-shell)
-* [`zurf config which`](#zurf-config-which)
-* [`zurf fetch URL`](#zurf-fetch-url)
-* [`zurf help [COMMAND]`](#zurf-help-command)
-* [`zurf init`](#zurf-init)
-* [`zurf plugins`](#zurf-plugins)
-* [`zurf plugins add PLUGIN`](#zurf-plugins-add-plugin)
-* [`zurf plugins:inspect PLUGIN...`](#zurf-pluginsinspect-plugin)
-* [`zurf plugins install PLUGIN`](#zurf-plugins-install-plugin)
-* [`zurf plugins link PATH`](#zurf-plugins-link-path)
-* [`zurf plugins remove [PLUGIN]`](#zurf-plugins-remove-plugin)
-* [`zurf plugins reset`](#zurf-plugins-reset)
-* [`zurf plugins uninstall [PLUGIN]`](#zurf-plugins-uninstall-plugin)
-* [`zurf plugins unlink [PLUGIN]`](#zurf-plugins-unlink-plugin)
-* [`zurf plugins update`](#zurf-plugins-update)
-* [`zurf search QUERY`](#zurf-search-query)
-
-## `zurf autocomplete [SHELL]`
-
-Display autocomplete installation instructions.
-
-```
-USAGE
-  $ zurf autocomplete [SHELL] [-r]
-
-ARGUMENTS
-  [SHELL]  (zsh|bash|powershell) Shell type
-
-FLAGS
-  -r, --refresh-cache  Refresh cache (ignores displaying instructions)
-
-DESCRIPTION
-  Display autocomplete installation instructions.
-
-EXAMPLES
-  $ zurf autocomplete
-
-  $ zurf autocomplete bash
-
-  $ zurf autocomplete zsh
-
-  $ zurf autocomplete powershell
-
-  $ zurf autocomplete --refresh-cache
-```
-
-_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v3.2.42/src/commands/autocomplete/index.ts)_
-
-## `zurf config which`
-
-Show where the API key is loaded from
-
-```
-USAGE
-  $ zurf config which [--json]
-
-FLAGS
-  --json  [env: ZURF_JSON] Print machine-readable JSON to stdout
-
-DESCRIPTION
-  Show where the API key is loaded from
-
-  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.
-
-EXAMPLES
-  $ zurf config which
-
-  $ zurf config which --json
-```
-
-_See code: [src/commands/config/which.ts](https://github.com/vibemastery/zurf/blob/v0.1.0/src/commands/config/which.ts)_
-
-## `zurf fetch URL`
-
-Fetch a URL via Browserbase
-
-```
-USAGE
-  $ zurf fetch URL [--json] [--allow-insecure-ssl] [--allow-redirects] [-o <value>] [--proxies]
-
-ARGUMENTS
-  URL  URL to fetch
-
-FLAGS
-  -o, --output=<value>      Write response body to this file (full content); otherwise human mode prints a truncated
-                            preview to stdout
-      --allow-insecure-ssl  Disable TLS certificate verification (use only if you trust the target)
-      --allow-redirects     Follow HTTP redirects
-      --json                [env: ZURF_JSON] Print machine-readable JSON to stdout
-      --proxies             Route through Browserbase proxies (helps with some blocked sites)
-
-DESCRIPTION
-  Fetch a URL via Browserbase
-
-  Fetch a URL via Browserbase (no browser session; static HTML, 1 MB max).
-  Requires authentication. Run `zurf init --global` or use a project key before first use.
-
-EXAMPLES
-  $ zurf fetch https://example.com
-
-  $ zurf fetch https://example.com --json
-
-  $ zurf fetch https://example.com -o page.html --proxies
-```
-
-_See code: [src/commands/fetch/index.ts](https://github.com/vibemastery/zurf/blob/v0.1.0/src/commands/fetch/index.ts)_
-
-## `zurf help [COMMAND]`
-
-Display help for zurf.
-
-```
-USAGE
-  $ zurf help [COMMAND...] [-n]
-
-ARGUMENTS
-  [COMMAND...]  Command to show help for.
-
-FLAGS
-  -n, --nested-commands  Include all nested commands in the output.
-
-DESCRIPTION
-  Display help for zurf.
-```
-
-_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/6.2.40/src/commands/help.ts)_
-
-## `zurf init`
-
-Configure Browserbase API key storage
-
-```
-USAGE
-  $ zurf init [--json] [--api-key <value>] [--gitignore] [--global] [--local]
-
-FLAGS
-  --api-key=<value>  API key for non-interactive use. Prefer piping stdin or using a TTY prompt — values on the command
-                     line are visible in shell history and process listings.
-  --gitignore        Append .zurf/ to ./.gitignore if that entry is missing
-  --global           Store API key in user config (oclif config dir for this CLI)
-  --json             [env: ZURF_JSON] Print machine-readable JSON to stdout
-  --local            Store API key in ./.zurf/config.json for this directory
-
-DESCRIPTION
-  Configure Browserbase API key storage
-
-  Save your Browserbase API key to global or project config.
-  Global path follows oclif config (same as `zurf config which`).
-
-EXAMPLES
-  $ zurf init --global
-
-  $ zurf init --local
-
-  printenv BROWSERBASE_API_KEY | zurf init --global
-```
-
-_See code: [src/commands/init/index.ts](https://github.com/vibemastery/zurf/blob/v0.1.0/src/commands/init/index.ts)_
-
-## `zurf plugins`
-
-List installed plugins.
-
-```
-USAGE
-  $ zurf plugins [--json] [--core]
-
-FLAGS
-  --core  Show core plugins.
-
-GLOBAL FLAGS
-  --json  Format output as json.
-
-DESCRIPTION
-  List installed plugins.
-
-EXAMPLES
-  $ zurf plugins
-```
-
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.59/src/commands/plugins/index.ts)_
-
-## `zurf plugins add PLUGIN`
-
-Installs a plugin into zurf.
-
-```
-USAGE
-  $ zurf plugins add PLUGIN... [--json] [-f] [-h] [-s | -v]
-
-ARGUMENTS
-  PLUGIN...  Plugin to install.
-
-FLAGS
-  -f, --force    Force npm to fetch remote resources even if a local copy exists on disk.
-  -h, --help     Show CLI help.
-  -s, --silent   Silences npm output.
-  -v, --verbose  Show verbose npm output.
-
-GLOBAL FLAGS
-  --json  Format output as json.
-
-DESCRIPTION
-  Installs a plugin into zurf.
-
-  Uses npm to install plugins.
-
-  Installation of a user-installed plugin will override a core plugin.
-
-  Use the ZURF_NPM_LOG_LEVEL environment variable to set the npm loglevel.
-  Use the ZURF_NPM_REGISTRY environment variable to set the npm registry.
-
-ALIASES
-  $ zurf plugins add
-
-EXAMPLES
-  Install a plugin from npm registry.
-
-    $ zurf plugins add myplugin
-
-  Install a plugin from a github url.
-
-    $ zurf plugins add https://github.com/someuser/someplugin
-
-  Install a plugin from a github slug.
-
-    $ zurf plugins add someuser/someplugin
-```
-
-## `zurf plugins:inspect PLUGIN...`
-
-Displays installation properties of a plugin.
-
-```
-USAGE
-  $ zurf plugins inspect PLUGIN...
-
-ARGUMENTS
-  PLUGIN...  [default: .] Plugin to inspect.
-
-FLAGS
-  -h, --help     Show CLI help.
-  -v, --verbose
-
-GLOBAL FLAGS
-  --json  Format output as json.
-
-DESCRIPTION
-  Displays installation properties of a plugin.
-
-EXAMPLES
-  $ zurf plugins inspect myplugin
-```
-
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.59/src/commands/plugins/inspect.ts)_
-
-## `zurf plugins install PLUGIN`
-
-Installs a plugin into zurf.
-
-```
-USAGE
-  $ zurf plugins install PLUGIN... [--json] [-f] [-h] [-s | -v]
-
-ARGUMENTS
-  PLUGIN...  Plugin to install.
-
-FLAGS
-  -f, --force    Force npm to fetch remote resources even if a local copy exists on disk.
-  -h, --help     Show CLI help.
-  -s, --silent   Silences npm output.
-  -v, --verbose  Show verbose npm output.
-
-GLOBAL FLAGS
-  --json  Format output as json.
-
-DESCRIPTION
-  Installs a plugin into zurf.
-
-  Uses npm to install plugins.
-
-  Installation of a user-installed plugin will override a core plugin.
-
-  Use the ZURF_NPM_LOG_LEVEL environment variable to set the npm loglevel.
-  Use the ZURF_NPM_REGISTRY environment variable to set the npm registry.
-
-ALIASES
-  $ zurf plugins add
-
-EXAMPLES
-  Install a plugin from npm registry.
-
-    $ zurf plugins install myplugin
-
-  Install a plugin from a github url.
-
-    $ zurf plugins install https://github.com/someuser/someplugin
-
-  Install a plugin from a github slug.
-
-    $ zurf plugins install someuser/someplugin
-```
-
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.59/src/commands/plugins/install.ts)_
-
-## `zurf plugins link PATH`
-
-Links a plugin into the CLI for development.
-
+$ zurf init --global          # save your Browserbase API key
+$ zurf --help
 ```
-USAGE
-  $ zurf plugins link PATH [-h] [--install] [-v]
-
-ARGUMENTS
-  PATH  [default: .] path to plugin
 
-FLAGS
-  -h, --help          Show CLI help.
-  -v, --verbose
-      --[no-]install  Install dependencies after linking the plugin.
+## Commands
 
-DESCRIPTION
-  Links a plugin into the CLI for development.
+### `zurf search <query>`
 
-  Installation of a linked plugin will override a user-installed or core plugin.
-
-  e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
-  command will override the user-installed or core plugin implementation. This is useful for development work.
-
-
-EXAMPLES
-  $ zurf plugins link myplugin
-```
-
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.59/src/commands/plugins/link.ts)_
-
-## `zurf plugins remove [PLUGIN]`
-
-Removes a plugin from the CLI.
+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
 ```
-USAGE
-  $ zurf plugins remove [PLUGIN...] [-h] [-v]
-
-ARGUMENTS
-  [PLUGIN...]  plugin to uninstall
 
-FLAGS
-  -h, --help     Show CLI help.
-  -v, --verbose
+| Flag | Description |
+|------|-------------|
+| `-n, --num-results` | Number of results, 1-25 (default: 10) |
+| `--json` | Print machine-readable JSON to stdout |
 
-DESCRIPTION
-  Removes a plugin from the CLI.
+### `zurf browse <url>`
 
-ALIASES
-  $ zurf plugins unlink
-  $ zurf plugins remove
+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.
 
-EXAMPLES
-  $ zurf plugins remove myplugin
-```
-
-## `zurf plugins reset`
-
-Remove all user-installed and linked plugins.
-
-```
-USAGE
-  $ zurf plugins reset [--hard] [--reinstall]
+Best for JavaScript-heavy pages (SPAs, dashboards, pages behind client-side rendering).
 
-FLAGS
-  --hard       Delete node_modules and package manager related files in addition to uninstalling plugins.
-  --reinstall  Reinstall all plugins after uninstalling.
+```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
 ```
 
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.59/src/commands/plugins/reset.ts)_
+| 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 plugins uninstall [PLUGIN]`
+### `zurf fetch <url>`
 
-Removes a plugin from the CLI.
+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
 ```
-USAGE
-  $ zurf plugins uninstall [PLUGIN...] [-h] [-v]
-
-ARGUMENTS
-  [PLUGIN...]  plugin to uninstall
 
-FLAGS
-  -h, --help     Show CLI help.
-  -v, --verbose
+| 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 |
 
-DESCRIPTION
-  Removes a plugin from the CLI.
+### `zurf init`
 
-ALIASES
-  $ zurf plugins unlink
-  $ zurf plugins remove
+Save your Browserbase API key and optional Project ID to a config file.
 
-EXAMPLES
-  $ zurf plugins uninstall myplugin
+```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
 ```
 
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.59/src/commands/plugins/uninstall.ts)_
-
-## `zurf plugins unlink [PLUGIN]`
+### `zurf config which`
 
-Removes a plugin from the CLI.
+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
 ```
-USAGE
-  $ zurf plugins unlink [PLUGIN...] [-h] [-v]
 
-ARGUMENTS
-  [PLUGIN...]  plugin to uninstall
+## Output format
 
-FLAGS
-  -h, --help     Show CLI help.
-  -v, --verbose
+`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.
 
-DESCRIPTION
-  Removes a plugin from the CLI.
+You can also set the default in `.zurf/config.json` or the global config:
 
-ALIASES
-  $ zurf plugins unlink
-  $ zurf plugins remove
-
-EXAMPLES
-  $ zurf plugins unlink myplugin
+```json
+{ "format": "html" }
 ```
 
-## `zurf plugins update`
-
-Update installed plugins.
+Format resolution (highest precedence first):
 
-```
-USAGE
-  $ zurf plugins update [-h] [-v]
+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`
 
-FLAGS
-  -h, --help     Show CLI help.
-  -v, --verbose
-
-DESCRIPTION
-  Update installed plugins.
-```
+## Configuration
 
-_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.59/src/commands/plugins/update.ts)_
+API key resolution (highest precedence first):
 
-## `zurf search QUERY`
+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`)
 
-Search the web via Browserbase
+Save a key interactively:
 
+```sh-session
+$ zurf init --global
+$ zurf init --local
 ```
-USAGE
-  $ zurf search QUERY [--json] [-n <value>]
-
-ARGUMENTS
-  QUERY  Search query, max 200 characters (quote for multiple words)
 
-FLAGS
-  -n, --num-results=<value>  [default: 10] Number of results (1–25)
-      --json                 [env: ZURF_JSON] Print machine-readable JSON to stdout
+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.
 
-DESCRIPTION
-  Search the web via Browserbase
+**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`.
 
-  Search the web via Browserbase (Exa-powered).
-  Requires authentication. Run `zurf init --global` or use a project key before first use.
+## Claude Code and agents
 
-EXAMPLES
-  $ zurf search "browserbase documentation"
+Install `zurf` on your `PATH` and allow the agent to run shell commands. Use `--json` when you want structured output:
 
-  $ zurf search "laravel inertia" --num-results 5 --json
+```sh-session
+$ zurf search "browserbase fetch api" --json
+$ zurf browse https://example.com --json
+$ zurf fetch https://example.com --json
 ```
 
-_See code: [src/commands/search/index.ts](https://github.com/vibemastery/zurf/blob/v0.1.0/src/commands/search/index.ts)_
-<!-- commandsstop -->
+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>;
+}