grok-search-cli 0.1.1

package/.env.example

@@ -0,0 +1,2 @@
+XAI_API_KEY=your_xai_api_key
+XAI_MODEL=grok-4-1-fast-non-reasoning

package/.env.openrouter.example

@@ -0,0 +1,3 @@
+XAI_API_KEY=your_openrouter_api_key
+XAI_MODEL=x-ai/grok-4.1-fast
+XAI_BASE_URL=https://openrouter.ai/api/v1

package/.env.yunwu.example

@@ -0,0 +1,4 @@
+XAI_API_KEY=your_yunwu_api_key
+XAI_MODEL=grok-4-fast
+XAI_BASE_URL=https://yunwu.ai/v1
+XAI_COMPAT_MODE=true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 timzhong
+
+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,147 @@
+# grok-search-cli
+
+[中文说明](./README.zh.md)
+
+Expose xAI Web + X search as a single CLI for agents that can run shell commands but do not integrate with xAI search APIs directly. It is built for prompts that need live web results, X discussion, and one-pass synthesis in the same call.
+
+## Get Started
+
+You only need two things to get it running: install the package, then provide the required environment variables.
+
+```bash
+pnpm add -g grok-search-cli
+```
+
+```env
+XAI_API_KEY=your_xai_api_key
+XAI_MODEL=grok-4-1-fast-non-reasoning
+# XAI_BASE_URL=https://your-proxy.example.com/v1 # optional proxy base URL
+# XAI_COMPAT_MODE=true # use OpenAI-compatible /chat/completions mode
+```
+
+Run it:
+
+```bash
+grok-search "latest xAI updates"
+```
+
+If you do not want a global install:
+
+```bash
+npx grok-search-cli "latest xAI updates"
+```
+
+Using OpenRouter:
+
+```env
+XAI_API_KEY=your_openrouter_api_key
+XAI_BASE_URL=https://openrouter.ai/api/v1
+XAI_MODEL=x-ai/grok-4-fast:online
+```
+
+With OpenRouter, the CLI auto-enables compatibility mode for the OpenAI-style endpoint and forwards OpenRouter web-search fields.
+
+## Use With Agents
+
+This repo ships with an installable skill:
+
+```bash
+npx skills add <owner>/<repo> --skill grok-search-cli
+```
+
+For Codex, use it as a research-agent preset: `gpt-5.4-mini` with `low` reasoning. See [agents/codex.yaml](./agents/codex.yaml).
+
+Trigger it with:
+
+```text
+Spawn a grok-research researcher agent with gpt-5.4-mini and low reasoning, then use grok-search for high-freshness web+X research.
+```
+
+## Provider Recommendations
+
+Recommended order:
+
+1. Use official xAI APIs when possible. This is the most direct and stable path for `web_search` and `x_search`.
+2. OpenRouter is also a solid option. Its web plugin can use native xAI search for xAI models, including both Web Search and X Search.
+3. If you use a third-party proxy, verify search support yourself. Many proxies only expose `/chat/completions`, and search only works if the proxy provider has enabled web search on their side.
+
+## Two Modes
+
+### xAI Official Mode
+
+Connect directly to xAI and use the Responses API with both tools enabled:
+
+- `xai.tools.webSearch()`
+- `xai.tools.xSearch()`
+
+This is the full-featured mode.
+
+### Proxy Mode
+
+If your gateway only supports OpenAI-style `/chat/completions`, enable compatibility mode:
+
+```env
+XAI_BASE_URL=https://your-proxy.example.com/v1
+XAI_COMPAT_MODE=true
+```
+
+In this mode the CLI switches to completion calls and does not explicitly register xAI tools.
+
+If `XAI_BASE_URL` points to OpenRouter, the CLI uses OpenRouter Responses API web search and sends OpenRouter-specific search fields.
+
+In compatibility mode:
+
+- actual search behavior depends on the proxy
+- tool-specific flags such as `--allowed-domains`, `--allowed-handles`, and `--from-date` are not forwarded; the CLI prints a warning if you pass them
+
+## Common Commands
+
+```bash
+grok-search "What are people saying about xAI on X right now?"
+```
+
+```bash
+grok-search "Somebody said xAI open-sourced model X today. Is that true?"
+```
+
+```bash
+grok-search "Find the latest arXiv papers and GitHub repos about browser-use agents"
+```
+
+```bash
+grok-search "latest AI SDK updates" \
+  --allowed-domains=ai-sdk.dev,vercel.com
+```
+
+```bash
+grok-search "latest xAI status on X" \
+  --allowed-handles=xai,elonmusk \
+  --from-date=2026-04-01
+```
+
+```bash
+grok-search "latest xAI updates" --json
+```
+
+```bash
+grok-search skill
+```
+
+The command prints the bundled skill to `stdout`, so it can also be redirected:
+
+```bash
+grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
+```
+
+```bash
+grok-search --help
+```
+
+## Local Development
+
+For local `.env` workflows, `pnpm dev` already runs through `dotenvx`:
+
+```bash
+pnpm install
+pnpm dev "latest xAI updates" --verbose
+```

package/README.zh.md

@@ -0,0 +1,147 @@
+# grok-search-cli
+
+[English](./README.md)
+
+把 xAI 的 Web + X 联合搜索能力暴露成一个通用 CLI，给只能调用命令行的 agent 用。适合那种既要看实时网页结果、又要看 X 讨论、还希望模型顺手做一轮综合判断的 prompt。
+
+## 跑起来
+
+最小依赖只有两件事：装包，然后提供所需环境变量。
+
+```bash
+pnpm add -g grok-search-cli
+```
+
+```env
+XAI_API_KEY=your_xai_api_key
+XAI_MODEL=grok-4-1-fast-non-reasoning
+# XAI_BASE_URL=https://your-proxy.example.com/v1 # optional proxy base URL
+# XAI_COMPAT_MODE=true # use OpenAI-compatible /chat/completions mode
+```
+
+直接跑：
+
+```bash
+grok-search "latest xAI updates"
+```
+
+如果不想全局安装：
+
+```bash
+npx grok-search-cli "latest xAI updates"
+```
+
+如果走 OpenRouter，可以直接这样配：
+
+```env
+XAI_API_KEY=your_openrouter_api_key
+XAI_BASE_URL=https://openrouter.ai/api/v1
+XAI_MODEL=x-ai/grok-4-fast:online
+```
+
+走 OpenRouter 时，CLI 会针对它的 OpenAI 风格接口自动开启兼容模式，并转发 OpenRouter 的 web search 字段。
+
+## 给 Agent 用
+
+这个仓库自带一个可安装 skill：
+
+```bash
+npx skills add <owner>/<repo> --skill grok-search-cli
+```
+
+如果是 Codex，推荐把它当成一个 research agent 约定来用：默认 `gpt-5.4-mini` + `low` reasoning，见 [agents/codex.yaml](./agents/codex.yaml)。
+
+可直接用这句触发：
+
+```text
+Spawn a grok-research researcher agent with gpt-5.4-mini and low reasoning, then use grok-search for high-freshness web+X research.
+```
+
+## 服务推荐
+
+推荐顺序：
+
+1. 优先使用 xAI 官方服务。这是 `web_search` 和 `x_search` 最直接、最稳定的路径。
+2. OpenRouter 也比较稳。它的 web 插件对 xAI 模型可以走原生 xAI 搜索，包含 Web Search 和 X Search。
+3. 如果使用第三方代理站，需要自己确认搜索能力。很多代理站只暴露 `/chat/completions`，是否真的能搜索，取决于站点是否在内部为你开启了 web search。
+
+## 两种模式
+
+### xAI 官方模式
+
+直接连 xAI 官方 API，使用 Responses API，并同时注册：
+
+- `xai.tools.webSearch()`
+- `xai.tools.xSearch()`
+
+这是能力最完整的模式。
+
+### 中转站模式
+
+如果你的 API 中转站只支持 OpenAI 风格的 `/chat/completions`，就打开兼容模式：
+
+```env
+XAI_BASE_URL=https://your-proxy.example.com/v1
+XAI_COMPAT_MODE=true
+```
+
+这时 CLI 会改走 completion 调用，不再显式注册 xAI tools。
+
+如果 `XAI_BASE_URL` 指向 OpenRouter，CLI 会走 OpenRouter 的 Responses API，并按 OpenRouter 的 web search 请求字段发送参数。
+
+兼容模式下：
+
+- 是否真的搜索、怎么搜索，由中转站决定
+- `--allowed-domains`、`--allowed-handles`、`--from-date` 这类 tool 参数不会下传；如果传了，CLI 会打印 warning
+
+## 常用命令
+
+```bash
+grok-search "现在 X 上大家都在怎么讨论 xAI？"
+```
+
+```bash
+grok-search "有人说 xAI 今天开源了某个模型，这是真的吗？"
+```
+
+```bash
+grok-search "找最新的 browser-use agents 相关 arXiv 论文和 GitHub 项目"
+```
+
+```bash
+grok-search "latest AI SDK updates" \
+  --allowed-domains=ai-sdk.dev,vercel.com
+```
+
+```bash
+grok-search "latest xAI status on X" \
+  --allowed-handles=xai,elonmusk \
+  --from-date=2026-04-01
+```
+
+```bash
+grok-search "latest xAI updates" --json
+```
+
+```bash
+grok-search skill
+```
+
+这个命令会把内置 skill 直接打印到 `stdout`，所以也可以重定向保存：
+
+```bash
+grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
+```
+
+```bash
+grok-search --help
+```
+
+## 本地开发
+
+本地如果要走 `.env`，`pnpm dev` 已经默认走 `dotenvx`：
+
+```bash
+pnpm install
+pnpm dev "latest xAI updates" --verbose
+```

package/agents/codex.yaml

@@ -0,0 +1,7 @@
+name: grok-research
+agent_type: researcher
+model: gpt-5.4-mini
+reasoning_effort: low
+description: >
+  Research-focused Codex preset for high-freshness web and X search through the
+  grok-search CLI.

package/dist/cli.js

@@ -0,0 +1,721 @@
+#!/usr/bin/env node
+import { generateText as e, streamText as t } from "ai";
+import { chmodSync as n, existsSync as r, mkdirSync as i, readFileSync as a, writeFileSync as o } from "node:fs";
+import s from "node:os";
+import c from "node:path";
+import l from "conf";
+import { createOpenAICompatible as ee } from "@ai-sdk/openai-compatible";
+import { createXai as te, xai as u } from "@ai-sdk/xai";
+import { fileURLToPath as ne } from "node:url";
+//#region src/config.ts
+var d = "grok-4-1-fast-non-reasoning", f = c.join(s.homedir(), ".config", "grok-search-cli");
+function p(e) {
+	return typeof e == "string" && e.trim() || void 0;
+}
+function m() {
+	return {
+		XAI_API_KEY: "",
+		XAI_MODEL: d,
+		XAI_BASE_URL: "",
+		XAI_COMPAT_MODE: !1,
+		_examples: {
+			xai: {
+				XAI_API_KEY: "your_xai_api_key",
+				XAI_MODEL: "grok-4-1-fast-non-reasoning"
+			},
+			openrouter: {
+				XAI_API_KEY: "your_openrouter_api_key",
+				XAI_MODEL: "x-ai/grok-4.1-fast",
+				XAI_BASE_URL: "https://openrouter.ai/api/v1"
+			},
+			yunwu: {
+				XAI_API_KEY: "your_yunwu_api_key",
+				XAI_MODEL: "grok-4-fast",
+				XAI_BASE_URL: "https://yunwu.ai/v1",
+				XAI_COMPAT_MODE: !0
+			}
+		}
+	};
+}
+function h() {
+	try {
+		return new l({
+			projectName: "grok-search-cli",
+			configName: "config",
+			cwd: f,
+			defaults: m()
+		});
+	} catch (e) {
+		let t = e instanceof Error ? e.message : String(e);
+		throw Error(`Failed to initialize user config: ${t}`);
+	}
+}
+var g = h(), _ = g.path;
+function v() {
+	if (i(c.dirname(_), { recursive: !0 }), !r(_)) {
+		o(_, `${JSON.stringify(m(), null, 2)}\n`, "utf8");
+		try {
+			n(_, 384);
+		} catch {}
+	}
+	return _;
+}
+function y() {
+	let e = g.store;
+	return {
+		apiKey: p(process.env.XAI_API_KEY) ?? e?.XAI_API_KEY,
+		model: p(process.env.XAI_MODEL) ?? e?.XAI_MODEL ?? d,
+		baseUrl: p(process.env.XAI_BASE_URL) ?? e?.XAI_BASE_URL,
+		compatModeRaw: process.env.XAI_COMPAT_MODE?.trim() ?? e?.XAI_COMPAT_MODE
+	};
+}
+function b() {
+	let e = g.store;
+	return {
+		apiKey: p(process.env.XAI_API_KEY) ? "env" : e?.XAI_API_KEY ? "config" : "missing",
+		model: p(process.env.XAI_MODEL) ? "env" : e?.XAI_MODEL ? "config" : "default",
+		baseUrl: p(process.env.XAI_BASE_URL) ? "env" : e?.XAI_BASE_URL ? "config" : "default",
+		compatMode: process.env.XAI_COMPAT_MODE?.trim() ? "env" : e?.XAI_COMPAT_MODE == null ? "default" : "config"
+	};
+}
+function x() {
+	return y().model;
+}
+function S() {
+	return y().apiKey;
+}
+function C() {
+	return y().baseUrl;
+}
+function re() {
+	let e = y(), t = b(), n = E(), r = T(e.baseUrl);
+	return {
+		configPath: _,
+		apiKeyPresent: !!e.apiKey,
+		model: e.model,
+		baseUrl: e.baseUrl,
+		providerKind: r,
+		apiMode: n,
+		sources: t
+	};
+}
+function w(e) {
+	if (!e) return !1;
+	try {
+		let { hostname: t } = new URL(e);
+		return t === "openrouter.ai" || t.endsWith(".openrouter.ai");
+	} catch {
+		return !1;
+	}
+}
+function T(e) {
+	if (!e) return "xai";
+	if (w(e)) return "openrouter";
+	try {
+		let { hostname: t } = new URL(e);
+		if (t === "x.ai" || t.endsWith(".x.ai")) return "xai";
+	} catch {}
+	return "third-party";
+}
+function ie() {
+	let { compatModeRaw: e, baseUrl: t } = y();
+	return T(t) !== "openrouter" && /^(1|true|yes|on)$/i.test(String(e || ""));
+}
+function E() {
+	return ie() ? "completion" : "responses";
+}
+function D(e) {
+	return T(C()) === "openrouter" && e === "responses" ? "OpenRouter Responses API Beta" : e === "responses" ? "xAI Responses API" : "OpenAI-compatible /chat/completions";
+}
+function O(e, t) {
+	if (e === "xai") {
+		console.error(t === "responses" ? "xAI Responses API request failed. Check XAI_API_KEY, model name, and search parameters." : "xAI-compatible completion request failed. Check XAI_API_KEY, model name, and gateway settings.");
+		return;
+	}
+	if (e === "openrouter") {
+		console.error("OpenRouter request failed. This CLI uses OpenRouter Responses API web search for openrouter.ai endpoints.");
+		return;
+	}
+	console.error("Third-party gateway request failed. Verify the gateway supports the selected API shape and that web search is enabled on the provider side.");
+}
+//#endregion
+//#region src/args.ts
+function k(e) {
+	process.stderr.write(`${e}\n`), process.exit(1);
+}
+function ae() {
+	let e = x();
+	process.stdout.write(`\
+Usage:
+  grok-search "<prompt>" [options]
+  grok-search skill
+  grok-search doctor
+
+Options:
+  skill                           Print the bundled skill to stdout
+  doctor                          Show config and credential diagnostics
+  --model=<id>                    Override model. Default: ${e}
+  --timeout=<seconds>             Request timeout. Default: 60
+  --json                          Output JSON
+  --verbose                       Print request and token diagnostics
+  --allowed-domains=a.com,b.com   Web Search allowed domains
+  --excluded-domains=a.com,b.com  Web Search excluded domains
+  --allowed-handles=xai,elonmusk  X Search allowed handles
+  --excluded-handles=spam1,spam2  X Search excluded handles
+  --from-date=YYYY-MM-DD          X Search start date
+  --to-date=YYYY-MM-DD            X Search end date
+  --image                         Enable image understanding
+  --video                         Enable video understanding for X Search
+  -h, --help                      Show this help
+
+Environment:
+  XAI_API_KEY                     Required
+`);
+}
+function oe(e) {
+	return e ? e.split(",").map((e) => e.trim()).filter(Boolean) : [];
+}
+function A(e, t, n) {
+	let r = e.indexOf("=");
+	return r >= 0 ? e.slice(r + 1) : t[n + 1];
+}
+function se() {
+	return {
+		model: x(),
+		timeoutMs: 6e4,
+		json: !1,
+		verbose: !1,
+		allowedDomains: [],
+		excludedDomains: [],
+		allowedHandles: [],
+		excludedHandles: [],
+		enableImageUnderstanding: !1,
+		enableVideoUnderstanding: !1
+	};
+}
+function j(e, t, n, r, i) {
+	let a = A(e, t, n)?.trim();
+	return a || k(`Missing value for ${r}`), i(a), e.includes("=") ? n : n + 1;
+}
+function M(e, t, n, r) {
+	return r(oe(A(e, t, n))), e.includes("=") ? n : n + 1;
+}
+function ce(e, t, n, r) {
+	let i = A(e, t, n)?.trim(), a = Number(i);
+	return (!i || !Number.isFinite(a) || a <= 0) && k("Invalid value for --timeout. Use a number of seconds > 0."), r.timeoutMs = Math.round(a * 1e3), e.includes("=") ? n : n + 1;
+}
+function N(e) {
+	let t = se(), n = [];
+	for (let r = 0; r < e.length; r += 1) {
+		let i = e[r];
+		if (!i.startsWith("-")) {
+			n.push(i);
+			continue;
+		}
+		if (i === "--json") {
+			t.json = !0;
+			continue;
+		}
+		if (i === "--verbose") {
+			t.verbose = !0;
+			continue;
+		}
+		if (i === "--image") {
+			t.enableImageUnderstanding = !0;
+			continue;
+		}
+		if (i === "--video") {
+			t.enableVideoUnderstanding = !0;
+			continue;
+		}
+		if (i.startsWith("--model")) {
+			r = j(i, e, r, "--model", (e) => {
+				t.model = e;
+			});
+			continue;
+		}
+		if (i.startsWith("--timeout")) {
+			r = ce(i, e, r, t);
+			continue;
+		}
+		if (i.startsWith("--allowed-domains")) {
+			r = M(i, e, r, (e) => {
+				t.allowedDomains = e;
+			});
+			continue;
+		}
+		if (i.startsWith("--excluded-domains")) {
+			r = M(i, e, r, (e) => {
+				t.excludedDomains = e;
+			});
+			continue;
+		}
+		if (i.startsWith("--allowed-handles")) {
+			r = M(i, e, r, (e) => {
+				t.allowedHandles = e;
+			});
+			continue;
+		}
+		if (i.startsWith("--excluded-handles")) {
+			r = M(i, e, r, (e) => {
+				t.excludedHandles = e;
+			});
+			continue;
+		}
+		if (i.startsWith("--from-date")) {
+			r = j(i, e, r, "--from-date", (e) => {
+				t.fromDate = e;
+			});
+			continue;
+		}
+		if (i.startsWith("--to-date")) {
+			r = j(i, e, r, "--to-date", (e) => {
+				t.toDate = e;
+			});
+			continue;
+		}
+		k(`Unknown option: ${i}`);
+	}
+	let r = n.join(" ").trim();
+	return r || k("Missing prompt."), t.allowedDomains.length > 0 && t.excludedDomains.length > 0 && k("Use either --allowed-domains or --excluded-domains, not both."), t.allowedHandles.length > 0 && t.excludedHandles.length > 0 && k("Use either --allowed-handles or --excluded-handles, not both."), {
+		command: "all",
+		prompt: r,
+		options: t
+	};
+}
+function P(e) {
+	if ((e.length === 0 || e.includes("--help") || e.includes("-h")) && (ae(), process.exit(0)), e[0] === "skill") {
+		let t = e.filter((e, t) => t > 0 && e.startsWith("-") && e !== "--help" && e !== "-h");
+		return t.length > 0 && k(`Unknown option: ${t[0]}`), { command: "skill" };
+	}
+	if (e[0] === "doctor") {
+		let t = e.filter((e, t) => t > 0 && e.startsWith("-") && e !== "--help" && e !== "-h");
+		return t.length > 0 && k(`Unknown option: ${t[0]}`), { command: "doctor" };
+	}
+	return N(e);
+}
+//#endregion
+//#region src/openrouter.ts
+function F(e) {
+	let t = {};
+	return e.allowedDomains.length > 0 && (t.allowed_domains = e.allowedDomains), e.excludedDomains.length > 0 && (t.excluded_domains = e.excludedDomains), I(t) ? {
+		type: "openrouter:web_search",
+		parameters: t
+	} : { type: "openrouter:web_search" };
+}
+function I(e) {
+	return Object.keys(e).length > 0;
+}
+function L(e, t, n) {
+	return {
+		model: t.model,
+		input: e,
+		tools: [F(t)],
+		stream: n
+	};
+}
+async function R(e) {
+	if (!e.ok) throw Error(await e.text());
+	return e;
+}
+function z(e) {
+	return (e.output?.find((e) => e.type === "message"))?.content?.find((e) => e.type === "output_text")?.text ?? "";
+}
+function B(e) {
+	return ((e.output?.find((e) => e.type === "message"))?.content?.find((e) => e.type === "output_text"))?.annotations?.filter((e) => e.type === "url_citation").map((e) => ({
+		sourceType: "url_citation",
+		url: e.url
+	})) ?? [];
+}
+function V(e) {
+	return {
+		inputTokens: e?.input_tokens,
+		outputTokens: e?.output_tokens,
+		totalTokens: e?.total_tokens,
+		outputTokenDetails: {
+			textTokens: e?.output_tokens,
+			reasoningTokens: void 0
+		}
+	};
+}
+function H(e) {
+	return {
+		text: z(e),
+		finishReason: e.status ?? "unknown",
+		usage: V(e.usage),
+		sources: B(e)
+	};
+}
+async function U(e) {
+	return R(await fetch(`${e.baseUrl}/responses`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${e.apiKey}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify(e.body),
+		signal: e.abortSignal
+	}));
+}
+function W(e) {
+	return (t) => ({
+		...t,
+		tools: [F(e)]
+	});
+}
+function G(e) {
+	if (!e.startsWith("data: ")) return { type: "ignore" };
+	let t = e.slice(6);
+	if (t === "[DONE]") return { type: "done" };
+	let n = JSON.parse(t);
+	return n.type === "response.output_text.delta" && typeof n.delta == "string" ? {
+		type: "delta",
+		text: n.delta
+	} : n.type === "response.completed" ? {
+		type: "completed",
+		response: n.response
+	} : { type: "ignore" };
+}
+async function le(e) {
+	return H(await (await U({
+		baseUrl: e.baseUrl,
+		apiKey: e.apiKey,
+		body: L(e.prompt, e.options, !1),
+		abortSignal: e.abortSignal
+	})).json());
+}
+async function ue(e) {
+	let t = (await U({
+		baseUrl: e.baseUrl,
+		apiKey: e.apiKey,
+		body: L(e.prompt, e.options, !0),
+		abortSignal: e.abortSignal
+	})).body?.getReader();
+	if (!t) throw Error("OpenRouter streaming response body is missing.");
+	let n = new TextDecoder(), r = "", i, a, o = new Promise((e, t) => {
+		i = e, a = t;
+	}), s = !1, c = (async function* () {
+		try {
+			for (;;) {
+				let { done: e, value: a } = await t.read();
+				if (e) break;
+				r += n.decode(a, { stream: !0 });
+				let o = r.split("\n");
+				r = o.pop() ?? "";
+				for (let e of o) {
+					let t = G(e);
+					if (t.type === "delta") {
+						yield t.text;
+						continue;
+					}
+					if (t.type === "completed") {
+						s = !0, i?.(t.response);
+						continue;
+					}
+					if (t.type === "done") return;
+				}
+			}
+			s || a?.(/* @__PURE__ */ Error("OpenRouter stream ended before response.completed."));
+		} catch (e) {
+			throw a?.(e), e;
+		}
+	})(), l = o.then(H);
+	return {
+		textStream: c,
+		text: l.then((e) => e.text),
+		finishReason: l.then((e) => e.finishReason),
+		usage: l.then((e) => e.usage),
+		sources: l.then((e) => e.sources)
+	};
+}
+//#endregion
+//#region src/output.ts
+function K({ model: e, finishReason: t, requestApi: n, baseUrl: r, durationMs: i, firstTokenLatencyMs: a, usage: o }) {
+	let s = o ?? {}, c = s.outputTokens, l = s.outputTokenDetails?.reasoningTokens;
+	return {
+		model: e,
+		finishReason: t,
+		requestApi: n,
+		baseUrl: r,
+		durationMs: i,
+		firstTokenLatencyMs: a,
+		tokensPerSecond: typeof c == "number" && i > 0 ? Number((c * 1e3 / i).toFixed(2)) : void 0,
+		usage: {
+			inputTokens: s.inputTokens,
+			outputTokens: c,
+			reasoningTokens: l,
+			totalTokens: s.totalTokens
+		}
+	};
+}
+function de(e) {
+	process.stdout.write("\nVerbose:\n"), process.stdout.write(`Model: ${e.model}\n`), process.stdout.write(`Finish reason: ${e.finishReason}\n`), process.stdout.write(`Request API: ${e.requestApi}\n`), e.baseUrl && process.stdout.write(`Base URL: ${e.baseUrl}\n`);
+	let t = [`Duration: ${(e.durationMs / 1e3).toFixed(2)}s`];
+	e.firstTokenLatencyMs != null && t.push(`first token ${(e.firstTokenLatencyMs / 1e3).toFixed(2)}s`), process.stdout.write(`${t.join(", ")}\n`);
+	let n = [
+		e.usage.inputTokens == null ? void 0 : `input=${e.usage.inputTokens}`,
+		e.usage.outputTokens == null ? void 0 : `output=${e.usage.outputTokens}`,
+		e.usage.reasoningTokens == null ? void 0 : `reasoning=${e.usage.reasoningTokens}`,
+		e.usage.totalTokens == null ? void 0 : `total=${e.usage.totalTokens}`
+	].filter(Boolean);
+	n.length > 0 && process.stdout.write(`Usage: ${n.join(", ")}\n`), e.tokensPerSecond != null && process.stdout.write(`TPS: ${e.tokensPerSecond}\n`);
+}
+function q(e) {
+	process.stdout.write(`${e.text}\n`), e.verbose && de(e.verbose);
+}
+async function fe(e) {
+	let t = !1, n = !1, r;
+	for await (let i of e.stream.textStream) r ??= Date.now() - e.startedAt, t = !0, n = i.endsWith("\n"), process.stdout.write(i);
+	(!t || !n) && process.stdout.write("\n");
+	let i = await e.stream.usage, a = await e.stream.finishReason ?? "unknown", o = {
+		...e.payload,
+		text: await e.stream.text,
+		finishReason: a,
+		usage: i ?? null,
+		sources: await e.stream.sources ?? [],
+		verbose: e.includeVerbose ? K({
+			model: e.payload.model,
+			finishReason: a,
+			requestApi: e.requestApi,
+			baseUrl: e.baseUrl,
+			durationMs: Date.now() - e.startedAt,
+			firstTokenLatencyMs: r,
+			usage: i
+		}) : void 0
+	};
+	process.stdout.write("\n"), q(o);
+}
+//#endregion
+//#region src/providers.ts
+function J(e) {
+	return {
+		web_search: u.tools.webSearch({
+			allowedDomains: e.allowedDomains.length > 0 ? e.allowedDomains : void 0,
+			excludedDomains: e.excludedDomains.length > 0 ? e.excludedDomains : void 0,
+			enableImageUnderstanding: e.enableImageUnderstanding || void 0
+		}),
+		x_search: u.tools.xSearch({
+			allowedXHandles: e.allowedHandles.length > 0 ? e.allowedHandles : void 0,
+			excludedXHandles: e.excludedHandles.length > 0 ? e.excludedHandles : void 0,
+			fromDate: e.fromDate,
+			toDate: e.toDate,
+			enableImageUnderstanding: e.enableImageUnderstanding || void 0,
+			enableVideoUnderstanding: e.enableVideoUnderstanding || void 0
+		})
+	};
+}
+function Y() {
+	let e = C();
+	return e ? te({ baseURL: e }) : u;
+}
+function X(e) {
+	let t = C();
+	return ee({
+		name: "compat",
+		apiKey: S(),
+		baseURL: t || "https://api.x.ai/v1",
+		transformRequestBody: w(t) ? W(e) : void 0
+	});
+}
+function pe(e) {
+	return e.allowedDomains.length > 0 || e.excludedDomains.length > 0 || e.allowedHandles.length > 0 || e.excludedHandles.length > 0 || typeof e.fromDate == "string" || typeof e.toDate == "string" || e.enableImageUnderstanding || e.enableVideoUnderstanding;
+}
+function me(e) {
+	return e.allowedHandles.length > 0 || e.excludedHandles.length > 0 || typeof e.fromDate == "string" || typeof e.toDate == "string" || e.enableImageUnderstanding || e.enableVideoUnderstanding;
+}
+//#endregion
+//#region src/skill.ts
+var Z = "grok-search-cli", he = ne(import.meta.url), Q = c.dirname(he);
+function ge(...e) {
+	let t = [c.resolve(Q, "..", "skills", Z, ...e), c.resolve(Q, "..", "..", "skills", Z, ...e)];
+	for (let e of t) try {
+		return a(e, "utf8");
+	} catch (e) {
+		if (e.code !== "ENOENT") throw e;
+	}
+	throw Error(`Bundled skill file not found for ${Z}: ${e.join("/")}`);
+}
+function _e() {
+	return ge("SKILL.md");
+}
+//#endregion
+//#region src/cli.ts
+function ve() {
+	let e = re();
+	if (process.stdout.write("Doctor:\n"), process.stdout.write(`Config path: ${e.configPath}\n`), process.stdout.write(`API key: ${e.apiKeyPresent ? "present" : "missing"} (${e.sources.apiKey})\n`), process.stdout.write(`Model: ${e.model} (${e.sources.model})\n`), process.stdout.write(`Base URL: ${e.baseUrl ?? "(xAI default)"} (${e.sources.baseUrl})\n`), process.stdout.write(`Compat mode source: ${e.sources.compatMode}\n`), process.stdout.write(`Provider: ${e.providerKind}\n`), process.stdout.write(`API mode: ${e.apiMode}\n`), process.stdout.write(`Status: ${e.apiKeyPresent ? "OK" : "NOT READY"}\n`), !e.apiKeyPresent) {
+		let e = v();
+		process.stdout.write(`Action: edit ${e}\n`);
+	}
+}
+function ye() {
+	let e = S();
+	return e || k(`Missing XAI_API_KEY.\n\nEdit ${v()} or set XAI_API_KEY in your shell environment.\nThis CLI reads credentials from process.env first, then ${_}.`), e;
+}
+function be(e, t) {
+	let n = C();
+	return e === "completion" && pe(t) && !w(n);
+}
+function xe(e, t) {
+	return $(e) && me(t);
+}
+function $(e) {
+	return T(C()) === "openrouter" && e === "responses";
+}
+function Se(e) {
+	return process.stdout.isTTY && !e;
+}
+function Ce(e) {
+	return {
+		command: e.command,
+		apiMode: e.apiMode,
+		model: e.model,
+		prompt: e.prompt,
+		text: e.result.text,
+		finishReason: e.result.finishReason ?? "unknown",
+		usage: e.result.usage ?? null,
+		sources: e.result.sources ?? [],
+		verbose: e.verbose ? K({
+			model: e.model,
+			finishReason: e.result.finishReason ?? "unknown",
+			requestApi: e.requestApi,
+			baseUrl: e.baseUrl,
+			durationMs: Date.now() - e.startedAt,
+			usage: e.result.usage ?? null
+		}) : void 0
+	};
+}
+function we(e) {
+	if (e.apiMode === "responses") {
+		let n = t({
+			model: Y().responses(e.model),
+			prompt: e.prompt,
+			tools: J(e.options),
+			abortSignal: e.abortSignal
+		});
+		return {
+			textStream: n.textStream,
+			text: n.text,
+			finishReason: n.finishReason,
+			usage: n.usage,
+			sources: n.sources
+		};
+	}
+	let n = t({
+		model: X(e.options)(e.model),
+		prompt: e.prompt,
+		abortSignal: e.abortSignal
+	});
+	return {
+		textStream: n.textStream,
+		text: n.text,
+		finishReason: n.finishReason,
+		usage: n.usage,
+		sources: n.sources
+	};
+}
+async function Te(t) {
+	if (t.apiMode === "responses") {
+		let n = await e({
+			model: Y().responses(t.model),
+			prompt: t.prompt,
+			tools: J(t.options),
+			abortSignal: t.abortSignal
+		});
+		return {
+			text: n.text,
+			finishReason: n.finishReason ?? "unknown",
+			usage: n.usage ?? null,
+			sources: n.sources ?? []
+		};
+	}
+	let n = await e({
+		model: X(t.options)(t.model),
+		prompt: t.prompt,
+		abortSignal: t.abortSignal
+	});
+	return {
+		text: n.text,
+		finishReason: n.finishReason ?? "unknown",
+		usage: n.usage ?? null,
+		sources: n.sources ?? []
+	};
+}
+async function Ee(e) {
+	await fe({
+		stream: $(e.apiMode) ? await ue({
+			prompt: e.prompt,
+			options: e.options,
+			baseUrl: e.baseUrl || "https://openrouter.ai/api/v1",
+			apiKey: e.apiKey,
+			abortSignal: e.abortSignal
+		}) : we(e),
+		payload: {
+			command: "all",
+			apiMode: e.apiMode,
+			model: e.model,
+			prompt: e.prompt
+		},
+		includeVerbose: e.options.verbose,
+		requestApi: e.requestApi,
+		baseUrl: e.baseUrl,
+		startedAt: e.startedAt
+	});
+}
+async function De(e) {
+	let t = $(e.apiMode) ? await le({
+		prompt: e.prompt,
+		options: e.options,
+		baseUrl: e.baseUrl || "https://openrouter.ai/api/v1",
+		apiKey: e.apiKey,
+		abortSignal: e.abortSignal
+	}) : await Te(e), n = Ce({
+		command: "all",
+		apiMode: e.apiMode,
+		model: e.model,
+		prompt: e.prompt,
+		result: t,
+		verbose: e.options.verbose,
+		requestApi: e.requestApi,
+		baseUrl: e.baseUrl,
+		startedAt: e.startedAt
+	});
+	if (e.options.json) {
+		process.stdout.write(`${JSON.stringify(n, null, 2)}\n`);
+		return;
+	}
+	q(n);
+}
+async function Oe() {
+	let e = P(process.argv.slice(2));
+	if (e.command === "skill") {
+		process.stdout.write(`${_e()}\n`);
+		return;
+	}
+	if (e.command === "doctor") {
+		ve();
+		return;
+	}
+	let t = ye(), n = E(), r = C(), i = D(n), a = Date.now(), o = AbortSignal.timeout(e.options.timeoutMs);
+	be(n, e.options) && console.error("Warning: compatibility mode is enabled, so tool-specific filters are not forwarded. Remove XAI_COMPAT_MODE to use xAI Responses API."), xe(n, e.options) && console.error("Warning: OpenRouter server-tool mode currently forwards web domain filters only. X-specific filters such as handles, dates, image, and video options are ignored.");
+	let s = {
+		prompt: e.prompt,
+		model: e.options.model,
+		apiMode: n,
+		options: e.options,
+		requestApi: i,
+		baseUrl: r,
+		startedAt: a,
+		abortSignal: o,
+		apiKey: t
+	};
+	if (Se(e.options.json)) {
+		await Ee(s);
+		return;
+	}
+	await De(s);
+}
+Oe().catch((e) => {
+	let t = e instanceof Error ? e.stack || e.message : String(e);
+	O(T(C()), E()), process.stderr.write(`${t}\n`), process.exit(1);
+});
+//#endregion

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "grok-search-cli",
+  "version": "0.1.1",
+  "description": "CLI for xAI webSearch and xSearch via the Vercel AI SDK provider.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "grok-search": "dist/cli.js"
+  },
+  "files": [
+    "agents",
+    "dist",
+    "skills",
+    "README.md",
+    "README.zh.md",
+    ".env.example",
+    ".env.openrouter.example",
+    ".env.yunwu.example"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@ai-sdk/openai-compatible": "^2.0.38",
+    "@ai-sdk/xai": "^3.0.77",
+    "ai": "^6.0.145",
+    "conf": "^14.0.0"
+  },
+  "devDependencies": {
+    "@dotenvx/dotenvx": "^1.51.1",
+    "@types/node": "^24.5.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.2",
+    "vite": "^8.0.3"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "dotenvx run -f .env -- tsx src/cli.ts"
+  }
+}

package/skills/grok-search-cli/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: grok-search-cli
+description: Use for high-freshness web+X research through a CLI, with Grok-backed synthesis plus JSON/citations output for agent workflows.
+---
+
+# grok-search-cli
+
+Use this skill when you need high-freshness search from a shell command and the runtime can invoke a CLI but does not natively integrate with xAI search tools.
+
+## Why Use It
+
+This CLI is useful because Grok search is strong on freshness.
+
+In xAI official mode, the CLI does not just call a plain search API and dump links back. It hands the research step to a Grok model with server-side search tools. In practice, that is close to letting a search-focused subagent go online, collect current results, and do one round of filtering and synthesis before the answer comes back.
+
+That makes this tool a good fit when you want current information with a lower hallucination risk than answering from stale memory.
+
+Especially consider this tool when searching:
+
+- X discussions and real-time public sentiment
+- GitHub repositories, release chatter, issue discussions, and ecosystem updates
+- papers, research announcements, and technical writeups
+- any current technical question where freshness matters more than raw recall
+
+## What It Does
+
+This skill exposes one CLI entrypoint for:
+
+- combined web + X search
+- JSON output for downstream agent processing
+
+## Choose the Right Mode
+
+### xAI official mode
+
+Use this when direct xAI access is available.
+
+Required environment:
+
+```bash
+export XAI_API_KEY=...
+```
+
+Optional:
+
+```bash
+export XAI_MODEL=grok-4-1-fast-non-reasoning
+```
+
+In this mode the CLI uses xAI Responses API server-side tools:
+
+- `xai.tools.webSearch()`
+- `xai.tools.xSearch()`
+
+### Proxy mode
+
+Use this when the endpoint only supports OpenAI-style `/chat/completions`.
+
+Required environment:
+
+```bash
+export XAI_API_KEY=...
+export XAI_BASE_URL=https://your-proxy.example.com/v1
+export XAI_COMPAT_MODE=true
+```
+
+Optional:
+
+```bash
+export XAI_MODEL=grok-4-1-fast-non-reasoning
+```
+
+In this mode the CLI falls back to completion calls. Tool-specific filters are not forwarded because search behavior depends on the proxy.
+
+## When To Reach For It
+
+Prefer this CLI over answering from memory when:
+
+- the user asks for the latest, current, recent, or today
+- the answer depends on X, GitHub, papers, release notes, or public web reporting
+- you want the model to search first and synthesize second
+- you want a smaller chance of hallucinating versions, timelines, or public discussion
+
+It is still a search-and-synthesis tool, not a perfect source of truth. For important claims, inspect the returned sources.
+
+## Command Patterns
+
+Default mode is combined web + X search:
+
+```bash
+grok-search "latest xAI updates"
+```
+
+Machine-readable output:
+
+```bash
+grok-search "latest xAI updates" --json
+```
+
+Useful filters in xAI official mode:
+
+```bash
+grok-search "latest AI SDK updates" --allowed-domains=ai-sdk.dev,vercel.com
+grok-search "latest xAI status" --allowed-handles=xai,elonmusk --from-date=2026-04-01
+```
+
+## When to Prefer This Skill
+
+- The agent can run shell commands but cannot call xAI APIs directly
+- You want one stable CLI for combined web and X research
+- You want citations or sources in stdout / JSON
+- You need a fallback path for OpenAI-compatible proxy endpoints
+- You want Grok to do one search/synthesis pass before the answer reaches the main agent
+
+## Notes
+
+- `--json` is the safest mode for agent consumption
+- In proxy mode, search is proxy-defined and tool-specific flags are ignored with a warning