@vibemastery/zurf 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Güette
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,541 @@
+zurf
+=================
+
+A lightweight CLI for searching 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)
+
+## 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`:
+
+```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.
+
+```
+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.
+
+DESCRIPTION
+  Links a plugin into the CLI for development.
+
+  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.
+
+```
+USAGE
+  $ zurf plugins remove [PLUGIN...] [-h] [-v]
+
+ARGUMENTS
+  [PLUGIN...]  plugin to uninstall
+
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
+
+DESCRIPTION
+  Removes a plugin from the CLI.
+
+ALIASES
+  $ zurf plugins unlink
+  $ zurf plugins remove
+
+EXAMPLES
+  $ zurf plugins remove myplugin
+```
+
+## `zurf plugins reset`
+
+Remove all user-installed and linked plugins.
+
+```
+USAGE
+  $ zurf plugins reset [--hard] [--reinstall]
+
+FLAGS
+  --hard       Delete node_modules and package manager related files in addition to uninstalling plugins.
+  --reinstall  Reinstall all plugins after uninstalling.
+```
+
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.59/src/commands/plugins/reset.ts)_
+
+## `zurf plugins uninstall [PLUGIN]`
+
+Removes a plugin from the CLI.
+
+```
+USAGE
+  $ zurf plugins uninstall [PLUGIN...] [-h] [-v]
+
+ARGUMENTS
+  [PLUGIN...]  plugin to uninstall
+
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
+
+DESCRIPTION
+  Removes a plugin from the CLI.
+
+ALIASES
+  $ zurf plugins unlink
+  $ zurf plugins remove
+
+EXAMPLES
+  $ zurf plugins uninstall myplugin
+```
+
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.59/src/commands/plugins/uninstall.ts)_
+
+## `zurf plugins unlink [PLUGIN]`
+
+Removes a plugin from the CLI.
+
+```
+USAGE
+  $ zurf plugins unlink [PLUGIN...] [-h] [-v]
+
+ARGUMENTS
+  [PLUGIN...]  plugin to uninstall
+
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
+
+DESCRIPTION
+  Removes a plugin from the CLI.
+
+ALIASES
+  $ zurf plugins unlink
+  $ zurf plugins remove
+
+EXAMPLES
+  $ zurf plugins unlink myplugin
+```
+
+## `zurf plugins update`
+
+Update installed plugins.
+
+```
+USAGE
+  $ zurf plugins update [-h] [-v]
+
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
+
+DESCRIPTION
+  Update installed plugins.
+```
+
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.59/src/commands/plugins/update.ts)_
+
+## `zurf search QUERY`
+
+Search the web via Browserbase
+
+```
+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
+
+DESCRIPTION
+  Search the web via Browserbase
+
+  Search the web via Browserbase (Exa-powered).
+  Requires authentication. Run `zurf init --global` or use a project key before first use.
+
+EXAMPLES
+  $ zurf search "browserbase documentation"
+
+  $ zurf search "laravel inertia" --num-results 5 --json
+```
+
+_See code: [src/commands/search/index.ts](https://github.com/vibemastery/zurf/blob/v0.1.0/src/commands/search/index.ts)_
+<!-- commandsstop -->

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node --loader ts-node/esm --no-warnings=ExperimentalWarning "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/* eslint-disable n/no-unsupported-features/node-builtins -- register ts-node ESM */
+/* eslint-disable n/no-unpublished-import -- dev bundle loads ../src */
+
+import {register} from 'node:module'
+import {dirname, join} from 'node:path'
+import {fileURLToPath, pathToFileURL} from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+register('ts-node/esm', pathToFileURL(`${root}/`))
+
+const {flush, handle, run, settings} = await import('@oclif/core')
+const {CliJsonExitContractError} = await import('../src/lib/cli-errors.js')
+
+process.env.NODE_ENV = 'development'
+settings.debug = true
+
+try {
+  await run(process.argv.slice(2), import.meta.url)
+} catch (error) {
+  if (error instanceof CliJsonExitContractError) {
+    process.exitCode = 1
+  } else {
+    await handle(error)
+  }
+} finally {
+  await flush()
+}

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import {flush, handle, run} from '@oclif/core'
+
+import {CliJsonExitContractError} from '../dist/lib/cli-errors.js'
+
+try {
+  await run(process.argv.slice(2), import.meta.url)
+} catch (error) {
+  if (error instanceof CliJsonExitContractError) {
+    process.exitCode = 1
+  } else {
+    await handle(error)
+  }
+} finally {
+  await flush()
+}

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

@@ -0,0 +1,10 @@
+import { Command } from '@oclif/core';
+export default class ConfigWhich extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    run(): Promise<void>;
+}

package/dist/commands/config/which.js

@@ -0,0 +1,61 @@
+import { Command } from '@oclif/core';
+import { globalConfigFilePath, resolveApiKey } from '../../lib/config.js';
+import { zurfBaseFlags } from '../../lib/flags.js';
+import { printJson } from '../../lib/json-output.js';
+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 examples = ['<%= config.bin %> config which', '<%= config.bin %> config which --json'];
+    static flags = {
+        ...zurfBaseFlags,
+    };
+    static summary = 'Show where the API key is loaded from';
+    async run() {
+        const { flags } = await this.parse(ConfigWhich);
+        const resolved = resolveApiKey({ 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;
+                }
+            }
+            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;
+            }
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+import { ZurfBrowserbaseCommand } from '../../lib/zurf-browserbase-command.js';
+export default class Fetch extends ZurfBrowserbaseCommand {
+    static args: {
+        url: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'allow-insecure-ssl': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        '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>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    run(): Promise<void>;
+}