webseek 0.3.0 → 0.5.0

package/README.md

@@ -19,6 +19,41 @@ The Gemini provider supports two backends that share the same request/response
 shape: the **Gemini Developer API** (`gemini-api`, default) and **Vertex AI
 express mode** (`vertex-express`).
 
+### Usage and cost
+
+Every search reports what it consumed and an estimated cost in USD. The text
+output ends with a line such as:
+
+```
+Usage: 1,100 tokens (1,000 in, 100 out), 1 search, ~$0.0180
+```
+
+JSON output (and the MCP tool result) carries the same data as `usage` and
+`cost`, plus the `model` that served the search:
+
+```jsonc
+{
+  "model": "gpt-5.5",
+  "usage": { "inputTokens": 1000, "outputTokens": 100, "totalTokens": 1100, "searchCalls": 1 },
+  "cost": { "totalUsd": 0.018, "tokensUsd": 0.008, "searchUsd": 0.01 },
+}
+```
+
+- `usage.inputTokens` includes cached tokens (`usage.cachedInputTokens`) and the
+  search content the model read; `usage.outputTokens` includes reasoning/thinking
+  tokens. SERP providers (`google`) report no tokens.
+- `usage.searchCalls` counts OpenAI `web_search` calls, Gemini grounding queries,
+  or Google Custom Search requests (one per page of 10 results).
+- `cost` is computed from built-in list prices: token rates for the model plus
+  the provider's search fee (OpenAI $10 per 1k calls, Gemini 3.x $14 per 1k
+  queries, Gemini 2.5 $35 per 1k grounded prompts, Google Custom Search $5 per 1k
+  queries). It is a list-price estimate, not your bill: free allowances,
+  discounts and long-context rates are **not** applied. `cost` is omitted when the model has no known price
+  or the provider reported no token counts.
+
+The CLI and the MCP server also append every successful search to a local usage
+log, which [`webseek stats`](#usage-stats) totals.
+
 ## Install
 
 ```bash
@@ -61,6 +96,54 @@ webseek "summarize the latest TypeScript release" -p openai
 webseek "who won euro 2024" -p gemini --gemini-backend vertex-express --json
 ```
 
+`mcp` and `stats` are subcommands: a query whose first word is `mcp` or
+`stats` must be quoted as a whole (`webseek "stats for the nba" -p openai`), and
+a query of just that one word cannot be searched from the CLI.
+
+### Usage stats
+
+Every successful search — from the CLI or the MCP server — is appended as one
+JSON line to `usage.jsonl` in the data directory: the time, provider, model,
+`usage` and `cost`. The query text is **not** stored. `webseek stats` totals
+the log, with flags modelled on `opencode stats`:
+
+```bash
+webseek stats                  # this year so far
+webseek stats --days 7 --full  # the last 7 days with every section
+webseek stats --all -p openai --models
+```
+
+```
+webseek stats · 2026 so far · all providers
+
+3 searches · 4 search calls · 12.9k tokens
+~$0.0550 estimated · 1 active day
+```
+
+| Flag                    | Description                                         |
+| ----------------------- | --------------------------------------------------- |
+| `--days <n>`            | The last N days; `0` means today                    |
+| `--year <year>`         | A calendar year (default: this year so far)         |
+| `--all`                 | Lifetime statistics                                 |
+| `-p, --provider <name>` | Only count one provider                             |
+| `--cost`                | Cost split (tokens / search fees) and token details |
+| `--models`              | Searches, tokens and cost per model                 |
+| `--full`                | Every detailed section                              |
+| `--limit <n>`           | Number of rows in the models section                |
+| `--json`                | Statistics as JSON                                  |
+
+`--days`, `--year` and `--all` cannot be combined. Costs are the same list-price
+estimates as in each search's output; searches whose model has no known price
+are counted but left out of the cost (and reported as unpriced).
+
+| Environment variable | Effect                                                                           |
+| -------------------- | -------------------------------------------------------------------------------- |
+| `WEBSEEK_DATA_DIR`   | Data directory (default `$XDG_DATA_HOME/webseek`, else `~/.local/share/webseek`) |
+| `WEBSEEK_USAGE_LOG`  | Set to `0`, `false` or `off` to stop recording searches                          |
+
+Delete `usage.jsonl` to reset the statistics. A failure to write the log is
+reported as a warning on stderr and never fails the search.
+
 ## MCP server mode
 
 Start a [Model Context Protocol](https://modelcontextprotocol.io) server over
@@ -105,8 +188,30 @@ CommonJS consumers can `require` it the same way:
 const { runSearch } = require("webseek");
 ```
 
+Each result carries `usage` and, when it can be priced, an estimated `cost` (see
+[Usage and cost](#usage-and-cost)). To price usage yourself — for example to sum
+several searches — call `estimateCost` with the provider, the model and a
+`usage` object; it returns `undefined` when the model has no known price:
+
+```ts
+import { estimateCost } from "webseek";
+
+const cost = estimateCost({
+  provider: "openai",
+  model: "gpt-5.5",
+  usage: { inputTokens: 1000, outputTokens: 100, searchCalls: 1 },
+});
+console.log(cost?.totalUsd.toFixed(3)); // "0.018"
+```
+
+Prices are list prices built into the package and change with its releases.
+
 To embed the `web_search` tool into your own MCP server, use the
-`createWebSearchTool` factory exported from the same entry point.
+`createWebSearchTool` factory exported from the same entry point. Its optional
+`onResult` callback receives every successful result (the `webseek mcp` server
+uses it to write the usage log).
+
+The library itself never writes the usage log; only the CLI and `webseek mcp` do.
 
 ## Authentication
 
@@ -135,10 +240,12 @@ they don't leak into shell history or process listings.
 ```
 src/
   index.ts    public library entry (runSearch, types, createWebSearchTool)
-  cli/        commander program: root search command and `mcp` command
+  cli/        commander program: root search command, `mcp` and `stats` commands
   mcp/        MCP server + the web_search tool
   lib/        runSearch — the shared core called by both CLI and MCP
   providers/  per-provider implementations (openai, google-cse, gemini)
+  pricing/    list-price table and cost estimation
+  stats/      local usage log, aggregation and the `stats` report
   config/     credential + base-URL resolution from env
   output/     text / JSON formatting
   utils/      logger, error formatter

package/dist/cli/index.cjs

@@ -1,10 +1,122 @@
 #!/usr/bin/env node
-const require_tools = require("../tools-Ci1EDrCT.cjs");
+const require_tools = require("../tools-Brr43TiA.cjs");
+let zod = require("zod");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 let commander = require("commander");
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
 let _modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
+let node_fs_promises = require("node:fs/promises");
+let node_os = require("node:os");
+//#region src/stats/usage-log.ts
+/**
+* The local usage log: one JSON line per successful search, appended by the
+* CLI and the MCP server and read back by `webseek stats`.
+*
+* Records hold what a search consumed and cost — never the query text — so the
+* log is safe to keep around. The library entry point never writes to it.
+*/
+const USAGE_LOG_FILE = "usage.jsonl";
+const RECORD_VERSION = 1;
+/**
+* The directory the usage log lives in: `WEBSEEK_DATA_DIR`, else
+* `$XDG_DATA_HOME/webseek`, else `~/.local/share/webseek`.
+*/
+function resolveDataDir(params = {}) {
+	const env = params.env ?? process.env;
+	if (env.WEBSEEK_DATA_DIR) return env.WEBSEEK_DATA_DIR;
+	if (env.XDG_DATA_HOME) return (0, node_path.join)(env.XDG_DATA_HOME, "webseek");
+	return (0, node_path.join)((0, node_os.homedir)(), ".local", "share", "webseek");
+}
+function resolveUsageLogPath(params = {}) {
+	return (0, node_path.join)(resolveDataDir(params), USAGE_LOG_FILE);
+}
+/** Logging is on unless `WEBSEEK_USAGE_LOG` is `0`, `false` or `off`. */
+function isUsageLogEnabled(params = {}) {
+	const value = (params.env ?? process.env).WEBSEEK_USAGE_LOG?.trim().toLowerCase();
+	return value !== "0" && value !== "false" && value !== "off";
+}
+function toUsageRecord(params) {
+	const { result } = params;
+	return {
+		v: RECORD_VERSION,
+		at: params.now ?? Date.now(),
+		provider: result.provider,
+		model: result.model,
+		usage: result.usage,
+		cost: result.cost
+	};
+}
+/**
+* Append a search to the usage log. Never throws: a failed write is reported
+* through `onError` so it cannot fail (or corrupt the output of) the search.
+*/
+async function appendUsageRecord(params) {
+	if (!isUsageLogEnabled({ env: params.env })) return;
+	try {
+		const dir = resolveDataDir({ env: params.env });
+		await (0, node_fs_promises.mkdir)(dir, {
+			recursive: true,
+			mode: 448
+		});
+		const record = toUsageRecord({
+			result: params.result,
+			now: params.now
+		});
+		await (0, node_fs_promises.appendFile)((0, node_path.join)(dir, USAGE_LOG_FILE), `${JSON.stringify(record)}\n`, {
+			encoding: "utf8",
+			mode: 384
+		});
+	} catch (error) {
+		params.onError?.(error);
+	}
+}
+/** Read every valid record from the usage log; a missing log reads as empty. */
+async function readUsageRecords(params = {}) {
+	let text;
+	try {
+		text = await (0, node_fs_promises.readFile)(resolveUsageLogPath(params), "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+	return parseUsageRecords(text);
+}
+const usageRecordSchema = zod.z.looseObject({
+	v: zod.z.literal(RECORD_VERSION),
+	at: zod.z.number(),
+	provider: zod.z.enum(require_tools.PROVIDER_NAMES),
+	model: zod.z.string().optional(),
+	usage: zod.z.looseObject({
+		inputTokens: zod.z.number().optional(),
+		cachedInputTokens: zod.z.number().optional(),
+		outputTokens: zod.z.number().optional(),
+		totalTokens: zod.z.number().optional(),
+		searchCalls: zod.z.number()
+	}).optional(),
+	cost: zod.z.looseObject({
+		totalUsd: zod.z.number(),
+		tokensUsd: zod.z.number(),
+		searchUsd: zod.z.number()
+	}).optional()
+});
+/** Parse JSONL, skipping blank, malformed and unknown-version lines. */
+function parseUsageRecords(text) {
+	const records = [];
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		let json;
+		try {
+			json = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		const parsed = usageRecordSchema.safeParse(json);
+		if (parsed.success) records.push(parsed.data);
+	}
+	return records;
+}
+//#endregion
 //#region src/mcp/server.ts
 /**
 * MCP server mode: exposes the `web_search` tool over the stdio transport so
@@ -17,7 +129,10 @@ async function startMcpServer(params) {
 		name: "webseek",
 		version: params.version
 	});
-	const tool = require_tools.createWebSearchTool();
+	const tool = require_tools.createWebSearchTool({ onResult: (result) => appendUsageRecord({
+		result,
+		onError: (error) => params.logger.warn(`could not record usage: ${require_tools.formatError(error)}`)
+	}) });
 	server.registerTool(tool.name, tool.config, tool.handler);
 	const transport = new _modelcontextprotocol_sdk_server_stdio_js.StdioServerTransport();
 	await server.connect(transport);
@@ -102,7 +217,10 @@ function formatJson(result) {
 		results: result.results,
 		answer: result.answer,
 		citations: result.citations,
-		searchQueries: result.searchQueries
+		searchQueries: result.searchQueries,
+		model: result.model,
+		usage: result.usage,
+		cost: result.cost
 	};
 	if (result.raw !== void 0) payload.raw = result.raw;
 	return JSON.stringify(payload, null, 2);
@@ -128,8 +246,29 @@ function formatText(result) {
 		lines.push("");
 	}
 	if (result.searchQueries.length > 0) lines.push(`Searches: ${result.searchQueries.join(" | ")}`);
+	if (result.usage) lines.push(formatUsage({
+		usage: result.usage,
+		cost: result.cost
+	}));
 	return lines.join("\n").trimEnd();
 }
+function formatUsage(params) {
+	const { usage, cost } = params;
+	const parts = [];
+	if (usage.inputTokens !== void 0 || usage.outputTokens !== void 0) {
+		const input = usage.inputTokens ?? 0;
+		const output = usage.outputTokens ?? 0;
+		const total = usage.totalTokens ?? input + output;
+		parts.push(`${total.toLocaleString("en-US")} tokens (${input.toLocaleString("en-US")} in, ${output.toLocaleString("en-US")} out)`);
+	}
+	parts.push(`${usage.searchCalls} search${usage.searchCalls === 1 ? "" : "es"}`);
+	parts.push(cost === void 0 ? "cost unknown" : `~${formatUsd(cost.totalUsd)}`);
+	return `Usage: ${parts.join(", ")}`;
+}
+function formatUsd(value) {
+	if (value > 0 && value < 5e-5) return "<$0.0001";
+	return `$${value.toFixed(4)}`;
+}
 //#endregion
 //#region src/cli/commands/search.ts
 /**
@@ -152,10 +291,15 @@ function toSearchRequest(params) {
 	};
 }
 async function runSearchCommand(params) {
-	const result = await require_tools.runSearch(toSearchRequest({
+	const request = toSearchRequest({
 		queryParts: params.queryParts,
 		options: params.options
-	}));
+	});
+	const result = await require_tools.runSearch(request);
+	await appendUsageRecord({
+		result,
+		onError: (error) => params.logger.warn(`could not record usage: ${require_tools.formatError(error)}`)
+	});
 	params.logger.result(formatResult({
 		result,
 		json: Boolean(params.options.json)
@@ -175,6 +319,293 @@ function registerSearchCommand(program) {
 	}));
 }
 //#endregion
+//#region src/stats/aggregate.ts
+/**
+* `--all` → all time; `--days N` → since local midnight N-1 days ago (0 or 1
+* mean today); `--year Y` → that calendar year; default → this year so far.
+*/
+function resolveStatsRange(params = {}) {
+	const now = params.now ?? /* @__PURE__ */ new Date();
+	const to = now.getTime() + 1;
+	if (params.all) return {
+		from: void 0,
+		to,
+		label: "all time"
+	};
+	if (params.days !== void 0) {
+		const from = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+		from.setDate(from.getDate() - Math.max(0, params.days - 1));
+		return {
+			from: from.getTime(),
+			to,
+			label: params.days <= 1 ? "today" : `last ${params.days} days`
+		};
+	}
+	const year = params.year ?? now.getFullYear();
+	const isCurrentYear = year === now.getFullYear();
+	return {
+		from: new Date(year, 0, 1).getTime(),
+		to: isCurrentYear ? to : new Date(year + 1, 0, 1).getTime(),
+		label: isCurrentYear ? `${year} so far` : String(year)
+	};
+}
+function aggregateUsage(params) {
+	const { range } = params;
+	const stats = {
+		range: {
+			from: range.from,
+			to: range.to
+		},
+		searches: 0,
+		searchCalls: 0,
+		tokens: {
+			input: 0,
+			cachedInput: 0,
+			output: 0,
+			total: 0
+		},
+		cost: {
+			totalUsd: 0,
+			tokensUsd: 0,
+			searchUsd: 0
+		},
+		unpricedSearches: 0,
+		activeDays: 0,
+		models: []
+	};
+	const days = /* @__PURE__ */ new Set();
+	const models = /* @__PURE__ */ new Map();
+	for (const record of params.records) {
+		if (!((range.from === void 0 || record.at >= range.from) && record.at < range.to) || params.provider !== void 0 && record.provider !== params.provider) continue;
+		addRecord({
+			stats,
+			models,
+			record
+		});
+		const at = new Date(record.at);
+		days.add(`${at.getFullYear()}-${at.getMonth()}-${at.getDate()}`);
+	}
+	stats.activeDays = days.size;
+	stats.models = [...models.values()].toSorted((a, b) => b.costUsd - a.costUsd || b.searches - a.searches);
+	return stats;
+}
+function addRecord(params) {
+	const { stats, record } = params;
+	const usage = record.usage;
+	const input = usage?.inputTokens ?? 0;
+	const output = usage?.outputTokens ?? 0;
+	const total = usage?.totalTokens ?? input + output;
+	const searchCalls = usage?.searchCalls ?? 0;
+	stats.searches += 1;
+	stats.searchCalls += searchCalls;
+	stats.tokens.input += input;
+	stats.tokens.cachedInput += usage?.cachedInputTokens ?? 0;
+	stats.tokens.output += output;
+	stats.tokens.total += total;
+	if (record.cost) {
+		stats.cost.totalUsd += record.cost.totalUsd;
+		stats.cost.tokensUsd += record.cost.tokensUsd;
+		stats.cost.searchUsd += record.cost.searchUsd;
+	} else stats.unpricedSearches += 1;
+	const key = `${record.provider}/${record.model ?? ""}`;
+	const model = params.models.get(key) ?? {
+		provider: record.provider,
+		model: record.model,
+		searches: 0,
+		searchCalls: 0,
+		tokens: 0,
+		costUsd: 0,
+		unpricedSearches: 0
+	};
+	model.searches += 1;
+	model.searchCalls += searchCalls;
+	model.tokens += total;
+	model.costUsd += record.cost?.totalUsd ?? 0;
+	if (!record.cost) model.unpricedSearches += 1;
+	params.models.set(key, model);
+}
+//#endregion
+//#region src/stats/render.ts
+/**
+* Renders aggregated usage as the `webseek stats` text report, laid out after
+* `opencode stats`: a summary by default, plus COST & TOKENS and MODELS
+* sections on request.
+*/
+function renderStats(params) {
+	const { stats } = params;
+	const detailed = params.cost || params.models;
+	const header = `webseek stats · ${params.label} · ${params.scope}`;
+	const lines = [];
+	if (detailed) lines.push(`${params.label} · ${params.scope}`);
+	else if (stats.searches === 0) lines.push(header, "", "no searches in this range");
+	else {
+		lines.push(header, "", `${plural({
+			value: stats.searches,
+			singular: "search",
+			pluralForm: "searches"
+		})} · ${plural({
+			value: stats.searchCalls,
+			singular: "search call"
+		})} · ${plural({
+			value: stats.tokens.total,
+			singular: "token"
+		})}`, `~${formatUsd(stats.cost.totalUsd)} estimated · ${plural({
+			value: stats.activeDays,
+			singular: "active day"
+		})}`);
+		if (stats.unpricedSearches > 0) lines.push(`${plural({
+			value: stats.unpricedSearches,
+			singular: "search",
+			pluralForm: "searches"
+		})} without a price estimate`);
+	}
+	if (params.cost) lines.push("", ...renderCost(stats));
+	if (params.models) lines.push("", ...renderModels({
+		models: stats.models,
+		limit: params.limit
+	}));
+	return lines.join("\n");
+}
+function renderCost(stats) {
+	const rows = [
+		["cost", `~${formatUsd(stats.cost.totalUsd)}`],
+		["  tokens", formatUsd(stats.cost.tokensUsd)],
+		["  search fees", formatUsd(stats.cost.searchUsd)],
+		["input", compact(stats.tokens.input)],
+		["cached input", compact(stats.tokens.cachedInput)],
+		["output", compact(stats.tokens.output)],
+		["search calls", compact(stats.searchCalls)]
+	];
+	if (stats.unpricedSearches > 0) rows.push(["unpriced searches", compact(stats.unpricedSearches)]);
+	return ["COST & TOKENS", ...rows.map(([label, value]) => `  ${label.padEnd(20)}${value}`)];
+}
+function renderModels(params) {
+	const { models, limit } = params;
+	if (models.length === 0) return ["MODELS", "  no searches"];
+	const shown = limit === void 0 ? models : models.slice(0, limit);
+	const rest = models.length - shown.length;
+	return [
+		"MODELS",
+		tableRow({
+			name: "model",
+			searches: "searches",
+			tokens: "tokens",
+			cost: "cost"
+		}),
+		...shown.map((model) => tableRow({
+			name: modelName(model),
+			searches: compact(model.searches),
+			tokens: compact(model.tokens),
+			cost: model.unpricedSearches === model.searches ? "-" : formatUsd(model.costUsd)
+		})),
+		...rest > 0 ? ["", `+${rest.toLocaleString("en-US")} more model${rest === 1 ? "" : "s"}`] : []
+	];
+}
+function modelName(model) {
+	const name = model.model?.replace(/\p{Cc}/gu, "");
+	return name ? `${model.provider}/${name}` : model.provider;
+}
+function tableRow(cells) {
+	return `${(cells.name.length <= 34 ? cells.name : `${cells.name.slice(0, 33)}…`).padEnd(34)}${cells.searches.padStart(10)}${cells.tokens.padStart(10)}${cells.cost.padStart(12)}`;
+}
+/** 1234 → "1.2k", 2_000_000 → "2m". */
+function compact(value) {
+	if (value >= 1e9) return `${oneDecimal(value / 1e9)}b`;
+	if (value >= 1e6) return `${oneDecimal(value / 1e6)}m`;
+	if (value >= 1e3) return `${oneDecimal(value / 1e3)}k`;
+	return Math.round(value).toLocaleString("en-US");
+}
+function oneDecimal(value) {
+	return value.toFixed(1).replace(/\.0$/, "");
+}
+function plural(params) {
+	const noun = params.value === 1 ? params.singular : params.pluralForm ?? `${params.singular}s`;
+	return `${compact(params.value)} ${noun}`;
+}
+//#endregion
+//#region src/cli/commands/stats.ts
+/** Validate CLI options into a stats request. Pure apart from reading `now`. */
+function toStatsRequest(params) {
+	const { options } = params;
+	if ([
+		options.days !== void 0,
+		options.year !== void 0,
+		options.all
+	].filter(Boolean).length > 1) throw new require_tools.WebseekError({
+		code: "invalid_usage",
+		message: "--days, --year, and --all cannot be combined."
+	});
+	return {
+		range: resolveStatsRange({
+			days: options.days === void 0 ? void 0 : parseInteger({
+				name: "days",
+				value: options.days,
+				min: 0,
+				max: 36500
+			}),
+			year: options.year === void 0 ? void 0 : parseInteger({
+				name: "year",
+				value: options.year,
+				min: 1970,
+				max: 9999
+			}),
+			all: options.all,
+			now: params.now
+		}),
+		provider: options.provider === void 0 ? void 0 : require_tools.coerceProvider(options.provider),
+		cost: Boolean(options.cost || options.full),
+		models: Boolean(options.models || options.full),
+		limit: options.limit === void 0 ? void 0 : parseInteger({
+			name: "limit",
+			value: options.limit,
+			min: 1,
+			max: Number.MAX_SAFE_INTEGER
+		}),
+		json: Boolean(options.json)
+	};
+}
+function parseInteger(params) {
+	const { name, value, min, max } = params;
+	const parsed = Number(value);
+	if (!/^\d+$/.test(value.trim()) || !Number.isSafeInteger(parsed) || parsed < min || parsed > max) throw new require_tools.WebseekError({
+		code: "invalid_usage",
+		message: `--${name} must be an integer between ${min} and ${max}.`
+	});
+	return parsed;
+}
+async function runStatsCommand(params) {
+	const request = toStatsRequest({ options: params.options });
+	const stats = aggregateUsage({
+		records: await readUsageRecords({ env: params.env }),
+		range: request.range,
+		provider: request.provider
+	});
+	if (request.json) {
+		const models = request.limit === void 0 ? stats.models : stats.models.slice(0, request.limit);
+		params.logger.result(JSON.stringify({
+			...stats,
+			models
+		}, null, 2));
+		return;
+	}
+	params.logger.result(renderStats({
+		stats,
+		label: request.range.label,
+		scope: request.provider ?? "all providers",
+		cost: request.cost,
+		models: request.models,
+		limit: request.limit
+	}));
+}
+function registerStatsCommand(program) {
+	program.command("stats").description("Show usage and estimated cost of the searches recorded locally").option("--days <n>", "show the last N days; 0 means today").option("--year <year>", "show a calendar year").option("--all", "show lifetime statistics").option("-p, --provider <name>", "only count one provider: openai | google | gemini").option("--cost", "show cost and token details").option("--models", "show usage per model").option("--full", "show every detailed section").option("--limit <n>", "number of rows in the models section").option("--json", "output statistics as JSON").action(wrapCommand(async ({ logger }, options) => {
+		await runStatsCommand({
+			logger,
+			options
+		});
+	}));
+}
+//#endregion
 //#region src/cli/index.ts
 /**
 * webseek CLI entry point.
@@ -182,6 +613,7 @@ function registerSearchCommand(program) {
 * Two modes:
 *   webseek <query> --provider <name>   run a one-off web search (root command)
 *   webseek mcp                         start the MCP server (stdio)
+*   webseek stats                       summarize the locally recorded usage
 */
 function readPackageVersion(dir) {
 	try {
@@ -203,12 +635,13 @@ function getVersion() {
 function buildProgram() {
 	const program = new commander.Command();
 	const version = getVersion();
-	program.name("webseek").description("Unified multi-provider web search (CLI + MCP server)").version(version, "-v, --version", "Show version");
+	program.name("webseek").description("Unified multi-provider web search (CLI + MCP server)").version(version, "-v, --version", "Show version").enablePositionalOptions();
 	registerSearchCommand(program);
 	registerMcpCommand({
 		program,
 		version
 	});
+	registerStatsCommand(program);
 	return program;
 }
 async function main() {