grok-search-cli 0.1.1 → 0.1.2

package/README.md

@@ -1,55 +1,118 @@
 # grok-search-cli
 
-[中文说明](./README.zh.md)
+[简体中文](./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.
+[![awesome for agents](https://img.shields.io/badge/awesome-for_agents-ff6b35)](https://github.com/timzhong1024/grok-search-cli)
+[![npm version](https://img.shields.io/npm/v/grok-search-cli)](https://www.npmjs.com/package/grok-search-cli)
+[![npm downloads](https://img.shields.io/npm/dm/grok-search-cli)](https://www.npmjs.com/package/grok-search-cli)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![node >= 22](https://img.shields.io/badge/node-%3E%3D22-339933)](https://nodejs.org/)
 
-## Get Started
 
-You only need two things to get it running: install the package, then provide the required environment variables.
+Make Grok's access to X and high-value public sources such as GitHub and arXiv available in any agent or shell workflow.
+
+This CLI makes that capability directly usable in agent workflows, with fresher information for fast-moving topics and far less operational overhead than building and maintaining a custom search stack.
+
+## Quick Start
+
+Install the package:
 
 ```bash
+# Install the CLI globally
 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 a health check:
+
+```bash
+# Check whether your config is ready
+grok-search doctor
+```
+
+If no config exists yet, the CLI creates:
+
+```text
+~/.config/grok-search-cli/config.json
+```
+
+Update the generated config file using one of the bundled examples. The default xAI official config is:
+
+```json
+{
+  "XAI_API_KEY": "your_xai_api_key",
+  "XAI_MODEL": "grok-4-1-fast-non-reasoning",
+  "XAI_BASE_URL": "",
+  "XAI_COMPAT_MODE": false
+}
 ```
 
-Run it:
+Run a query:
 
 ```bash
+# Run a first search
 grok-search "latest xAI updates"
 ```
 
-If you do not want a global install:
+If you do not want a global install, you can run it with `npx`:
 
 ```bash
+# Run without a global install
+npx grok-search-cli doctor
 npx grok-search-cli "latest xAI updates"
 ```
 
-Using OpenRouter:
+## What You Can Ask
 
-```env
-XAI_API_KEY=your_openrouter_api_key
-XAI_BASE_URL=https://openrouter.ai/api/v1
-XAI_MODEL=x-ai/grok-4-fast:online
+```bash
+# Search current discussion on X
+grok-search "What are people saying about xAI on X right now?"
 ```
 
-With OpenRouter, the CLI auto-enables compatibility mode for the OpenAI-style endpoint and forwards OpenRouter web-search fields.
+```bash
+# Verify a fresh rumor or claim
+grok-search "Somebody said xAI open-sourced model X today. Is that true?"
+```
+
+```bash
+# Search papers and repos together
+grok-search "Find the latest arXiv papers and GitHub repos about browser-use agents"
+```
+
+```bash
+# Constrain web results to specific domains
+grok-search "latest AI SDK updates" \
+  --allowed-domains=ai-sdk.dev,vercel.com
+```
+
+```bash
+# Constrain X results by handle and date
+grok-search "latest xAI status on X" \
+  --allowed-handles=xai,elonmusk \
+  --from-date=2026-04-01
+```
+
+```bash
+# Return machine-readable JSON
+grok-search "latest xAI updates" --json
+```
+
+## Why Use It
+
+- Research what is happening now, not what the base model remembers
+- Search the web and X in one call
+- Return clean terminal output or JSON for agents
+- Work with xAI, OpenRouter, or compatible gateways
 
 ## Use With Agents
 
 This repo ships with an installable skill:
 
 ```bash
-npx skills add <owner>/<repo> --skill grok-search-cli
+# Install the bundled skill with the skills CLI
+npx skills add timzhong1024/grok-search-cli --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).
+For Codex, a matching preset is included at [agents/codex.yaml](./agents/codex.yaml).
 
 Trigger it with:
 
@@ -57,83 +120,98 @@ Trigger it with:
 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:
+The bundled skill can also be printed to `stdout` and redirected:
 
-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.
+```bash
+# Print the bundled skill and save it manually
+grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
+```
 
-## Two Modes
+## Configuration
 
-### xAI Official Mode
+`process.env` takes priority over `~/.config/grok-search-cli/config.json`, so shell env is the easiest way to override config temporarily.
 
-Connect directly to xAI and use the Responses API with both tools enabled:
+### xAI Official
 
-- `xai.tools.webSearch()`
-- `xai.tools.xSearch()`
+```json
+{
+  "XAI_API_KEY": "your_xai_api_key",
+  "XAI_MODEL": "grok-4-1-fast-non-reasoning",
+  "XAI_BASE_URL": "",
+  "XAI_COMPAT_MODE": false
+}
+```
 
-This is the full-featured mode.
+### OpenRouter
 
-### Proxy Mode
+```json
+{
+  "XAI_API_KEY": "your_openrouter_api_key",
+  "XAI_MODEL": "x-ai/grok-4-fast:online",
+  "XAI_BASE_URL": "https://openrouter.ai/api/v1",
+  "XAI_COMPAT_MODE": false
+}
+```
 
-If your gateway only supports OpenAI-style `/chat/completions`, enable compatibility mode:
+### Yunwu / Other Compatible Gateways
 
-```env
-XAI_BASE_URL=https://your-proxy.example.com/v1
-XAI_COMPAT_MODE=true
+```json
+{
+  "XAI_API_KEY": "your_proxy_api_key",
+  "XAI_MODEL": "grok-4-fast",
+  "XAI_BASE_URL": "https://yunwu.ai/v1",
+  "XAI_COMPAT_MODE": true
+}
 ```
 
-In this mode the CLI switches to completion calls and does not explicitly register xAI tools.
+## Provider Guide
 
-If `XAI_BASE_URL` points to OpenRouter, the CLI uses OpenRouter Responses API web search and sends OpenRouter-specific search fields.
+Recommended order:
 
-In compatibility mode:
+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. It can use native xAI-backed web search for xAI models.
+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.
 
-- 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
+## Search Modes
 
-## Common Commands
+### xAI Official
 
-```bash
-grok-search "What are people saying about xAI on X right now?"
-```
+Use this when you connect directly to xAI.
 
-```bash
-grok-search "Somebody said xAI open-sourced model X today. Is that true?"
-```
+- Supports both web search and X search
+- Supports web domain filters, X handle filters, date filters, and image or video understanding options
+- Best choice when you want the full feature set
 
-```bash
-grok-search "Find the latest arXiv papers and GitHub repos about browser-use agents"
-```
+### OpenRouter
 
-```bash
-grok-search "latest AI SDK updates" \
-  --allowed-domains=ai-sdk.dev,vercel.com
-```
+Use this when `XAI_BASE_URL` points to `openrouter.ai`.
 
-```bash
-grok-search "latest xAI status on X" \
-  --allowed-handles=xai,elonmusk \
-  --from-date=2026-04-01
-```
+- Supports web search through OpenRouter's server-side search tool
+- Supports web domain filters
+- Does not currently forward X-specific filters such as handles, dates, image, or video options
 
-```bash
-grok-search "latest xAI updates" --json
-```
+### Other Compatible Gateways
+
+Use this when you connect through another OpenAI-compatible gateway with `XAI_COMPAT_MODE=true`.
+
+- Uses the gateway's compatibility path
+- Search behavior depends on the gateway
+- Tool-specific filters are not forwarded, so advanced search controls may not be available
+
+## CLI Reference
 
 ```bash
-grok-search skill
+# Check whether your config is ready
+grok-search doctor
 ```
 
-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
+# Print the bundled skill to stdout
+grok-search skill
 ```
 
 ```bash
+# Show all CLI options
 grok-search --help
 ```
 
@@ -142,6 +220,7 @@ grok-search --help
 For local `.env` workflows, `pnpm dev` already runs through `dotenvx`:
 
 ```bash
+# Run the TypeScript entrypoint through dotenvx in development
 pnpm install
 pnpm dev "latest xAI updates" --verbose
 ```

package/README.zh.md

@@ -2,54 +2,116 @@
 
 [English](./README.md)
 
-把 xAI 的 Web + X 联合搜索能力暴露成一个通用 CLI，给只能调用命令行的 agent 用。适合那种既要看实时网页结果、又要看 X 讨论、还希望模型顺手做一轮综合判断的 prompt。
+[![awesome for agents](https://img.shields.io/badge/awesome-for_agents-ff6b35)](https://github.com/timzhong1024/grok-search-cli)
+[![npm version](https://img.shields.io/npm/v/grok-search-cli)](https://www.npmjs.com/package/grok-search-cli)
+[![npm downloads](https://img.shields.io/npm/dm/grok-search-cli)](https://www.npmjs.com/package/grok-search-cli)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![node >= 22](https://img.shields.io/badge/node-%3E%3D22-339933)](https://nodejs.org/)
 
-## 跑起来
+把 Grok 对 X 以及 GitHub、arXiv 等高价值公开数据源的访问能力，带到任何 agent 和 shell 工作流里。
 
-最小依赖只有两件事：装包，然后提供所需环境变量。
+这个 CLI 让这套能力可以直接用于 agent 工作流：在处理快速变化的话题时，更容易获得更新鲜的信息，同时显著降低自建和维护搜索能力的成本。
+
+## 快速开始
+
+先安装：
 
 ```bash
+# 全局安装 CLI
 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 doctor
+```
+
+如果本地还没有配置文件，CLI 会自动创建：
+
+```text
+~/.config/grok-search-cli/config.json
+```
+
+打开这个文件，并按内置示例更新配置。默认的 xAI 官方配置如下：
+
+```json
+{
+  "XAI_API_KEY": "your_xai_api_key",
+  "XAI_MODEL": "grok-4-1-fast-non-reasoning",
+  "XAI_BASE_URL": "",
+  "XAI_COMPAT_MODE": false
+}
 ```
 
-直接跑：
+然后执行查询：
 
 ```bash
+# 先跑一个最基本的搜索
 grok-search "latest xAI updates"
 ```
 
-如果不想全局安装：
+如果不想全局安装，也可以通过 `npx` 运行：
 
 ```bash
+# 不全局安装，直接用 npx 运行
+npx grok-search-cli doctor
 npx grok-search-cli "latest xAI updates"
 ```
 
-如果走 OpenRouter，可以直接这样配：
+## 可以怎么搜
+
+```bash
+# 看看现在 X 上都在怎么讨论 xAI
+grok-search "现在 X 上大家都在怎么讨论 xAI？"
+```
+
+```bash
+# 验证一个刚出现的说法是不是真的
+grok-search "有人说 xAI 今天开源了某个模型，这是真的吗？"
+```
+
+```bash
+# 一次找论文和 GitHub 项目
+grok-search "找最新的 browser-use agents 相关 arXiv 论文和 GitHub 项目"
+```
+
+```bash
+# 把网页搜索限制在指定站点
+grok-search "latest AI SDK updates" \
+  --allowed-domains=ai-sdk.dev,vercel.com
+```
+
+```bash
+# 按账号和日期限制 X 搜索范围
+grok-search "latest xAI status on X" \
+  --allowed-handles=xai,elonmusk \
+  --from-date=2026-04-01
+```
 
-```env
-XAI_API_KEY=your_openrouter_api_key
-XAI_BASE_URL=https://openrouter.ai/api/v1
-XAI_MODEL=x-ai/grok-4-fast:online
+```bash
+# 返回适合 agent 消费的 JSON
+grok-search "latest xAI updates" --json
 ```
 
-走 OpenRouter 时，CLI 会针对它的 OpenAI 风格接口自动开启兼容模式，并转发 OpenRouter 的 web search 字段。
+## 为什么用它
+
+- 查“现在发生了什么”，而不是赌模型记忆有没有过时
+- 一次调用同时看网页和 X
+- 终端可直接读，agent 也能吃 JSON
+- 可接 xAI、OpenRouter 和兼容代理站
 
 ## 给 Agent 用
 
 这个仓库自带一个可安装 skill：
 
 ```bash
-npx skills add <owner>/<repo> --skill grok-search-cli
+# 用 skills CLI 安装仓库自带的 skill
+npx skills add timzhong1024/grok-search-cli --skill grok-search-cli
 ```
 
-如果是 Codex，推荐把它当成一个 research agent 约定来用：默认 `gpt-5.4-mini` + `low` reasoning，见 [agents/codex.yaml](./agents/codex.yaml)。
+如果是 Codex，仓库里还带了一份可配套使用的 preset，见 [agents/codex.yaml](./agents/codex.yaml)。
 
 可直接用这句触发：
 
@@ -57,83 +119,98 @@ npx skills add <owner>/<repo> --skill grok-search-cli
 Spawn a grok-research researcher agent with gpt-5.4-mini and low reasoning, then use grok-search for high-freshness web+X research.
 ```
 
-## 服务推荐
+内置 skill 也可以直接打印到 `stdout` 后手动安装：
 
-推荐顺序：
-
-1. 优先使用 xAI 官方服务。这是 `web_search` 和 `x_search` 最直接、最稳定的路径。
-2. OpenRouter 也比较稳。它的 web 插件对 xAI 模型可以走原生 xAI 搜索，包含 Web Search 和 X Search。
-3. 如果使用第三方代理站，需要自己确认搜索能力。很多代理站只暴露 `/chat/completions`，是否真的能搜索，取决于站点是否在内部为你开启了 web search。
+```bash
+# 把内置 skill 打印出来并手动保存
+grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
+```
 
-## 两种模式
+## 配置方式
 
-### xAI 官方模式
+`process.env` 的优先级高于 `~/.config/grok-search-cli/config.json`，因此在临时覆盖配置时，优先使用 shell 环境变量。
 
-直接连 xAI 官方 API，使用 Responses API，并同时注册：
+### xAI 官方
 
-- `xai.tools.webSearch()`
-- `xai.tools.xSearch()`
+```json
+{
+  "XAI_API_KEY": "your_xai_api_key",
+  "XAI_MODEL": "grok-4-1-fast-non-reasoning",
+  "XAI_BASE_URL": "",
+  "XAI_COMPAT_MODE": false
+}
+```
 
-这是能力最完整的模式。
+### OpenRouter
 
-### 中转站模式
+```json
+{
+  "XAI_API_KEY": "your_openrouter_api_key",
+  "XAI_MODEL": "x-ai/grok-4-fast:online",
+  "XAI_BASE_URL": "https://openrouter.ai/api/v1",
+  "XAI_COMPAT_MODE": false
+}
+```
 
-如果你的 API 中转站只支持 OpenAI 风格的 `/chat/completions`，就打开兼容模式：
+### yunwu / 其他兼容代理站
 
-```env
-XAI_BASE_URL=https://your-proxy.example.com/v1
-XAI_COMPAT_MODE=true
+```json
+{
+  "XAI_API_KEY": "your_proxy_api_key",
+  "XAI_MODEL": "grok-4-fast",
+  "XAI_BASE_URL": "https://yunwu.ai/v1",
+  "XAI_COMPAT_MODE": true
+}
 ```
 
-这时 CLI 会改走 completion 调用，不再显式注册 xAI tools。
+## 服务选择建议
 
-如果 `XAI_BASE_URL` 指向 OpenRouter，CLI 会走 OpenRouter 的 Responses API，并按 OpenRouter 的 web search 请求字段发送参数。
+推荐顺序：
 
-兼容模式下：
+1. 优先使用 xAI 官方服务。这是 `web_search` 和 `x_search` 最直接、最稳定的路径。
+2. OpenRouter 也比较稳。它对 xAI 模型可以走原生 xAI 支持的 web search。
+3. 如果使用第三方代理站，需要自己确认搜索能力。很多代理站只暴露 `/chat/completions`，是否真的能搜索，取决于站点是否在内部为你开启了 web search。
 
-- 是否真的搜索、怎么搜索，由中转站决定
-- `--allowed-domains`、`--allowed-handles`、`--from-date` 这类 tool 参数不会下传；如果传了，CLI 会打印 warning
+## 搜索模式
 
-## 常用命令
+### xAI 官方
 
-```bash
-grok-search "现在 X 上大家都在怎么讨论 xAI？"
-```
+直接连接 xAI 官方服务时使用。
 
-```bash
-grok-search "有人说 xAI 今天开源了某个模型，这是真的吗？"
-```
+- 同时支持 Web Search 和 X Search
+- 支持网页域名过滤、X 账号过滤、日期过滤，以及图片或视频理解选项
+- 这是能力最完整的模式
 
-```bash
-grok-search "找最新的 browser-use agents 相关 arXiv 论文和 GitHub 项目"
-```
+### OpenRouter
 
-```bash
-grok-search "latest AI SDK updates" \
-  --allowed-domains=ai-sdk.dev,vercel.com
-```
+当 `XAI_BASE_URL` 指向 `openrouter.ai` 时使用。
 
-```bash
-grok-search "latest xAI status on X" \
-  --allowed-handles=xai,elonmusk \
-  --from-date=2026-04-01
-```
+- 支持通过 OpenRouter 的服务端搜索工具进行网页搜索
+- 只支持网页域名过滤
+- **不支持**配置 X 专属配置，例如账号、日期、以及图片或视频理解选项
 
-```bash
-grok-search "latest xAI updates" --json
-```
+### 其他兼容网关
+
+当你通过其他 OpenAI-compatible 网关接入，并启用 `XAI_COMPAT_MODE=true` 时使用。
+
+- 使用网关提供的兼容调用路径
+- 是否真的搜索、怎么搜索，由中转站决定
+- 不支持所有搜索高级配置
+
+## CLI 参考
 
 ```bash
-grok-search skill
+# 检查当前配置是否可用
+grok-search doctor
 ```
 
-这个命令会把内置 skill 直接打印到 `stdout`，所以也可以重定向保存：
-
 ```bash
-grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
+# 把内置 skill 打印到 stdout
+grok-search skill
 ```
 
 ```bash
+# 查看完整命令帮助
 grok-search --help
 ```
 
@@ -142,6 +219,7 @@ grok-search --help
 本地如果要走 `.env`，`pnpm dev` 已经默认走 `dotenvx`：
 
 ```bash
+# 开发时通过 dotenvx 运行 TypeScript 入口
 pnpm install
 pnpm dev "latest xAI updates" --verbose
 ```

package/dist/cli.js

@@ -148,12 +148,12 @@ function ae() {
 	process.stdout.write(`\
 Usage:
   grok-search "<prompt>" [options]
-  grok-search skill
   grok-search doctor
+  grok-search skill
 
 Options:
-  skill                           Print the bundled skill to stdout
   doctor                          Show config and credential diagnostics
+  skill                           Print the bundled skill to stdout
   --model=<id>                    Override model. Default: ${e}
   --timeout=<seconds>             Request timeout. Default: 60
   --json                          Output JSON

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "grok-search-cli",
-  "version": "0.1.1",
-  "description": "CLI for xAI webSearch and xSearch via the Vercel AI SDK provider.",
+  "version": "0.1.2",
+  "description": "AI-friendly CLI for high-freshness web and X research with Grok search tool.",
+  "keywords": [
+    "agent",
+    "agentic",
+    "ai",
+    "cli",
+    "grok",
+    "llm",
+    "research",
+    "search",
+    "web-search",
+    "x-search",
+    "x",
+    "xai",
+    "freshness",
+    "real-time",
+    "github",
+    "shell"
+  ],
   "license": "MIT",
   "type": "module",
   "bin": {