Add 'wrangler websearch search' command

Adds a new top-level 'websearch' namespace with a single 'search'
subcommand:

  npx wrangler websearch search <query>
  npx wrangler websearch search <query> --limit 5
  npx wrangler websearch search <query> --json

Both --limit and --json are optional. limit defaults to 10 server-side
and is capped at 20. Without --json the results render as a pretty
table (#, title, url, description, lastModified); with --json the raw
response body is printed verbatim.

The command POSTs to /accounts/{accountId}/websearch/search with body
{ query, limit? } and uses requireAuth(config) for credentials, same
pattern as 'wrangler ai-search search'.

* src/websearch/types.ts: response shape (items + metadata)
* src/websearch/client.ts: fetchResult wrapper
* src/websearch/index.ts: namespace metadata
* src/websearch/search.ts: command definition
* src/index.ts: registry.define + registerNamespace
* src/core/teams.d.ts: add 'Product: Web Search' to the Teams enum
* src/utils/add-created-resource-config.ts: exclude 'web_search' from
  ValidKeys (singleton bindings can't go through the createdResource
  config helper; same exclusion as 'ai' and 'browser')
* src/__tests__/index.test.ts: update top-level help snapshot to
  include the new namespace
* .changeset: document the new command

Author: G4brym

.changeset/add-web-search-binding.md

@@ -16,4 +16,14 @@ Cloudflare Web Search is a managed, zero-setup web discovery primitive for agent
 
 There is exactly one shared web corpus, so there is no namespace, instance, or other field to specify -- only the variable name. The binding exposes a single `search()` method that returns URLs and catalog metadata for a query. Web Search is discovery-only -- to read a result's content the caller invokes the global `fetch()` API against the result's `url`.
 
-The binding is **always remote** in local development: Miniflare proxies to the production Web Search service via the remote-bindings transport. Adds the `websearch:read` OAuth scope to `wrangler login`.
+The binding is **always remote** in local development: Miniflare proxies to the production Web Search service via the remote-bindings transport. Adds the `websearch:run` OAuth scope to `wrangler login`.
+
+Also adds a `wrangler websearch search` command for running ad-hoc queries from the CLI:
+
+```sh
+npx wrangler websearch search "cloudflare workers"
+npx wrangler websearch search "cloudflare workers" --limit 5
+npx wrangler websearch search "cloudflare workers" --json
+```
+
+`--limit` is optional (defaults to 10, capped at 20). `--json` prints the raw response; without it the results render as a pretty table.

packages/wrangler/src/__tests__/index.test.ts

@@ -69,6 +69,7 @@ describe("wrangler", () => {
 				  wrangler types [path]           📝 Generate types from your Worker configuration
 				  wrangler versions               🫧 List, view, upload and deploy Versions of your Worker to Cloudflare
 				  wrangler vpc                    🌐 Manage VPC [open beta]
+				  wrangler websearch              🔎 Run queries against Cloudflare Web Search [open beta]
 				  wrangler workflows              🔁 Manage Workflows
 
 				STORAGE & DATABASES
@@ -146,6 +147,7 @@ describe("wrangler", () => {
 				  wrangler types [path]           📝 Generate types from your Worker configuration
 				  wrangler versions               🫧 List, view, upload and deploy Versions of your Worker to Cloudflare
 				  wrangler vpc                    🌐 Manage VPC [open beta]
+				  wrangler websearch              🔎 Run queries against Cloudflare Web Search [open beta]
 				  wrangler workflows              🔁 Manage Workflows
 
 				STORAGE & DATABASES

packages/wrangler/src/core/teams.d.ts

@@ -15,6 +15,7 @@ export type Teams =
 	| "Product: Queues"
 	| "Product: AI"
 	| "Product: AI Search"
+	| "Product: Web Search"
 	| "Product: Hyperdrive"
 	| "Product: Pipelines"
 	| "Product: Vectorize"

packages/wrangler/src/index.ts

@@ -441,6 +441,8 @@ import { vpcServiceGetCommand } from "./vpc/get";
 import { vpcNamespace, vpcServiceNamespace } from "./vpc/index";
 import { vpcServiceListCommand } from "./vpc/list";
 import { vpcServiceUpdateCommand } from "./vpc/update";
+import { webSearchNamespace } from "./websearch/index";
+import { webSearchSearchCommand } from "./websearch/search";
 import { workflowsInstanceNamespace, workflowsNamespace } from "./workflows";
 import { workflowsDeleteCommand } from "./workflows/commands/delete";
 import { workflowsDescribeCommand } from "./workflows/commands/describe";
@@ -1443,6 +1445,16 @@ export function createCLIParser(argv: string[]) {
 	]);
 	registry.registerNamespace("ai-search");
 
+	// websearch
+	registry.define([
+		{ command: "wrangler websearch", definition: webSearchNamespace },
+		{
+			command: "wrangler websearch search",
+			definition: webSearchSearchCommand,
+		},
+	]);
+	registry.registerNamespace("websearch");
+
 	// cert - includes mtls-certificates and CA cert management
 	registry.define([
 		{ command: "wrangler cert", definition: certNamespace },

packages/wrangler/src/utils/add-created-resource-config.ts

@@ -20,6 +20,7 @@ type ValidKeys = Exclude<
 	ConfigBindingFieldName,
 	| "ai"
 	| "browser"
+	| "web_search"
 	| "vars"
 	| "wasm_modules"
 	| "text_blobs"

packages/wrangler/src/websearch/client.ts

@@ -0,0 +1,22 @@
+import { fetchResult } from "../cfetch";
+import { requireAuth } from "../user";
+import type { WebSearchSearchResponse } from "./types";
+import type { Config } from "@cloudflare/workers-utils";
+
+const jsonContentType = "application/json; charset=utf-8;";
+
+export async function search(
+	config: Config,
+	body: { query: string; limit?: number }
+): Promise<WebSearchSearchResponse> {
+	const accountId = await requireAuth(config);
+	return await fetchResult<WebSearchSearchResponse>(
+		config,
+		`/accounts/${accountId}/websearch/search`,
+		{
+			method: "POST",
+			headers: { "content-type": jsonContentType },
+			body: JSON.stringify(body),
+		}
+	);
+}

packages/wrangler/src/websearch/index.ts

@@ -0,0 +1,10 @@
+import { createNamespace } from "../core/create-command";
+
+export const webSearchNamespace = createNamespace({
+	metadata: {
+		description: "🔎 Run queries against Cloudflare Web Search",
+		status: "open beta",
+		owner: "Product: Web Search",
+		category: "Compute & AI",
+	},
+});

packages/wrangler/src/websearch/search.ts

@@ -0,0 +1,69 @@
+import { createCommand } from "../core/create-command";
+import { logger } from "../logger";
+import { search } from "./client";
+
+export const webSearchSearchCommand = createCommand({
+	metadata: {
+		description: "Run a query against Cloudflare Web Search",
+		status: "open beta",
+		owner: "Product: Web Search",
+	},
+	behaviour: {
+		printBanner: (args) => !args.json,
+	},
+	args: {
+		query: {
+			type: "string",
+			demandOption: true,
+			description: "The search query text.",
+		},
+		limit: {
+			type: "number",
+			description:
+				"Maximum number of results to return (defaults to 10, capped at 20).",
+		},
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Return output as clean JSON",
+		},
+	},
+	positionalArgs: ["query"],
+	async handler(args, { config }) {
+		const body: { query: string; limit?: number } = { query: args.query };
+		if (args.limit !== undefined) {
+			body.limit = args.limit;
+		}
+
+		const result = await search(config, body);
+
+		if (args.json) {
+			logger.log(JSON.stringify(result, null, 2));
+			return;
+		}
+
+		logger.log(
+			`Search query: "${result.metadata.query}"  (${result.items.length} results, ${result.metadata.latencyMs}ms, request ${result.metadata.requestId})\n`
+		);
+
+		if (result.items.length === 0) {
+			logger.log("No results found.");
+			return;
+		}
+
+		logger.table(
+			result.items.map((item, i) => ({
+				"#": String(i + 1),
+				title:
+					item.title.length > 60 ? item.title.slice(0, 60) + "..." : item.title,
+				url: item.url.length > 80 ? item.url.slice(0, 80) + "..." : item.url,
+				description: item.description
+					? item.description.length > 80
+						? item.description.slice(0, 80) + "..."
+						: item.description
+					: "",
+				lastModified: item.lastModifiedDate ?? "",
+			}))
+		);
+	},
+});

packages/wrangler/src/websearch/types.ts

@@ -0,0 +1,44 @@
+/**
+ * A single Web Search result.
+ *
+ * Web Search is discovery-only -- results carry catalog metadata about a page
+ * but never the page body. To read a result's content, fetch the URL yourself.
+ */
+export interface WebSearchResult {
+	/** Canonical URL. */
+	url: string;
+	/** Page title. */
+	title: string;
+	/** Page-level description. May be absent. */
+	description?: string;
+	/**
+	 * Last-modified date for the page, when known. Naive (no timezone)
+	 * ISO-8601 datetime, e.g. "2025-11-30T04:39:48".
+	 */
+	lastModifiedDate?: string;
+	/** Page meta image URL (typically og:image). May be absent. */
+	imageUrl?: string;
+	/** Optional favicon URL for UI hints. */
+	faviconUrl?: string;
+}
+
+/**
+ * Per-response metadata for a Web Search query. Carries operational fields
+ * useful for support and debugging.
+ */
+export interface WebSearchResponseMetadata {
+	/** The query that was executed. */
+	query: string;
+	/** Opaque request identifier used for support and debugging. */
+	requestId: string;
+	/** End-to-end latency for this search request, in milliseconds. */
+	latencyMs: number;
+}
+
+/**
+ * Response from a Web Search query.
+ */
+export interface WebSearchSearchResponse {
+	items: WebSearchResult[];
+	metadata: WebSearchResponseMetadata;
+}