grok-search-cli 0.1.1 → 0.1.3

package/README.md

@@ -1,55 +1,117 @@
 # 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
 ```
 
-Run it:
+If no config exists yet, the CLI creates:
+
+```text
+~/.config/grok-search-cli/config.json
+```
+
+In most cases, you only need to set an API key from [xAI](https://x.ai/api):
+
+```json
+{
+  "XAI_API_KEY": "your_xai_api_key"
+}
+```
+
+If you are using a non-official provider, see [Configuration](#configuration).
+
+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 +119,115 @@ 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
+The bundled skill can also be printed to `stdout` and redirected:
 
-Recommended order:
+```bash
+# Print the bundled skill and save it manually
+grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
+```
 
-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.
+## Configuration
 
-## Two Modes
+`process.env` takes priority over `~/.config/grok-search-cli/config.json`, so shell env is the easiest way to override config temporarily.
 
-### xAI Official Mode
+By default, the CLI uses the official xAI endpoint and the built-in default model `grok-4-1-fast-non-reasoning`.
 
-Connect directly to xAI and use the Responses API with both tools enabled:
+| Field | Required | Default behavior | When you might override it |
+| --- | --- | --- | --- |
+| `XAI_API_KEY` | Yes | No default | Required in all cases |
+| `XAI_MODEL` | No | Uses `grok-4-1-fast-non-reasoning` | When you want a different Grok model |
+| `XAI_BASE_URL` | No | Uses the official xAI endpoint | When routing through OpenRouter or another compatible gateway |
 
-- `xai.tools.webSearch()`
-- `xai.tools.xSearch()`
+If you want to override the model:
 
-This is the full-featured mode.
+```json
+{
+  "XAI_API_KEY": "your_xai_api_key",
+  "XAI_MODEL": "grok-4-1-fast-non-reasoning"
+}
+```
 
-### Proxy Mode
+Important: model IDs are provider-specific. The official xAI model ID, the OpenRouter model ID, and the model ID expected by another compatible gateway may not match. If you switch providers, check the provider's expected model name instead of reusing the previous one unchanged.
 
-If your gateway only supports OpenAI-style `/chat/completions`, enable compatibility mode:
+### OpenRouter Example
 
-```env
-XAI_BASE_URL=https://your-proxy.example.com/v1
-XAI_COMPAT_MODE=true
+```json
+{
+  "XAI_API_KEY": "your_openrouter_api_key",
+  "XAI_MODEL": "x-ai/grok-4.1-fast",
+  "XAI_BASE_URL": "https://openrouter.ai/api/v1"
+}
 ```
 
-In this mode the CLI switches to completion calls and does not explicitly register xAI tools.
+### Other Compatible Gateway Example
 
-If `XAI_BASE_URL` points to OpenRouter, the CLI uses OpenRouter Responses API web search and sends OpenRouter-specific search fields.
+```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 compatibility mode:
+For gateways such as yunwu, set `XAI_COMPAT_MODE=true`.
 
-- 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
+## Provider Guide
 
-## Common Commands
+Recommended order:
 
-```bash
-grok-search "What are people saying about xAI on X right now?"
-```
+1. Use official xAI APIs when possible. This is the most direct and stable path for `web_search` and `x_search`.
+2. OpenRouter is the best fallback when you do not want to use xAI directly. It is the most predictable non-official option here.
+3. Third-party compatible gateways such as yunwu are a compatibility fallback. 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
-grok-search "Somebody said xAI open-sourced model X today. Is that true?"
-```
+Recommended model choices:
 
-```bash
-grok-search "Find the latest arXiv papers and GitHub repos about browser-use agents"
-```
+| Provider | Recommended model | Why |
+| --- | --- | --- |
+| xAI official | `grok-4-1-fast-non-reasoning` | Default path in this CLI, best support for `web_search` and `x_search` |
+| OpenRouter | `x-ai/grok-4.1-fast` | Best default when routing through OpenRouter |
+| Other compatible gateways such as yunwu | Provider-specific | Use the model ID your gateway actually exposes, for example `grok-4-fast` on yunwu |
 
-```bash
-grok-search "latest AI SDK updates" \
-  --allowed-domains=ai-sdk.dev,vercel.com
-```
+## Search Modes
 
-```bash
-grok-search "latest xAI status on X" \
-  --allowed-handles=xai,elonmusk \
-  --from-date=2026-04-01
-```
+### xAI Official
 
-```bash
-grok-search "latest xAI updates" --json
-```
+Use this when you connect directly to xAI.
+
+- 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
+
+### OpenRouter
+
+Use this when `XAI_BASE_URL` points to `openrouter.ai`.
+
+- 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
+
+### Other Compatible Gateways
+
+Use this when you connect through another OpenAI-compatible gateway.
+
+- 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 +236,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,115 @@
 
 [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](https://x.ai/api) 获取的 API key：
+
+```json
+{
+  "XAI_API_KEY": "your_xai_api_key"
+}
 ```
 
-直接跑：
+如果你使用的是非官方提供商，见下方的[配置方式](#配置方式)。
+
+然后执行查询：
 
 ```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？"
+```
 
-```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
+# 验证一个刚出现的说法是不是真的
+grok-search "有人说 xAI 今天开源了某个模型，这是真的吗？"
 ```
 
-走 OpenRouter 时，CLI 会针对它的 OpenAI 风格接口自动开启兼容模式，并转发 OpenRouter 的 web search 字段。
+```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
+```
+
+```bash
+# 返回适合 agent 消费的 JSON
+grok-search "latest xAI updates" --json
+```
+
+## 为什么用它
+
+- 查“现在发生了什么”，而不是赌模型记忆有没有过时
+- 一次调用同时看网页和 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 +118,115 @@ 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` 后手动安装：
 
-推荐顺序：
+```bash
+# 把内置 skill 打印出来并手动保存
+grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
+```
 
-1. 优先使用 xAI 官方服务。这是 `web_search` 和 `x_search` 最直接、最稳定的路径。
-2. OpenRouter 也比较稳。它的 web 插件对 xAI 模型可以走原生 xAI 搜索，包含 Web Search 和 X Search。
-3. 如果使用第三方代理站，需要自己确认搜索能力。很多代理站只暴露 `/chat/completions`，是否真的能搜索，取决于站点是否在内部为你开启了 web search。
+## 配置方式
 
-## 两种模式
+`process.env` 的优先级高于 `~/.config/grok-search-cli/config.json`，因此在临时覆盖配置时，优先使用 shell 环境变量。
 
-### xAI 官方模式
+默认情况下，CLI 会使用 xAI 官方地址和内置默认模型 `grok-4-1-fast-non-reasoning`。
 
-直接连 xAI 官方 API，使用 Responses API，并同时注册：
+| 字段 | 是否必填 | 默认行为 | 什么时候可能要改 |
+| --- | --- | --- | --- |
+| `XAI_API_KEY` | 是 | 无默认值 | 所有场景都必须提供 |
+| `XAI_MODEL` | 否 | 使用 `grok-4-1-fast-non-reasoning` | 当你想切换到其他 Grok 模型时 |
+| `XAI_BASE_URL` | 否 | 使用 xAI 官方地址 | 当你要接 OpenRouter 或其他兼容网关时 |
 
-- `xai.tools.webSearch()`
-- `xai.tools.xSearch()`
+如果你想手动覆盖模型，可以这样写：
 
-这是能力最完整的模式。
+```json
+{
+  "XAI_API_KEY": "your_xai_api_key",
+  "XAI_MODEL": "grok-4-1-fast-non-reasoning"
+}
+```
 
-### 中转站模式
+注意：不同服务商使用的 model id 不一定一样。xAI 官方、OpenRouter、以及其他兼容网关，通常都需要各自对应的模型名。切换服务商时，不要直接沿用原来的 model id。
 
-如果你的 API 中转站只支持 OpenAI 风格的 `/chat/completions`，就打开兼容模式：
+### OpenRouter 示例
 
-```env
-XAI_BASE_URL=https://your-proxy.example.com/v1
-XAI_COMPAT_MODE=true
+```json
+{
+  "XAI_API_KEY": "your_openrouter_api_key",
+  "XAI_MODEL": "x-ai/grok-4.1-fast",
+  "XAI_BASE_URL": "https://openrouter.ai/api/v1"
+}
 ```
 
-这时 CLI 会改走 completion 调用，不再显式注册 xAI tools。
+### 其他兼容网关示例
 
-如果 `XAI_BASE_URL` 指向 OpenRouter，CLI 会走 OpenRouter 的 Responses API，并按 OpenRouter 的 web search 请求字段发送参数。
+```json
+{
+  "XAI_API_KEY": "your_proxy_api_key",
+  "XAI_MODEL": "grok-4-fast",
+  "XAI_BASE_URL": "https://yunwu.ai/v1",
+  "XAI_COMPAT_MODE": true
+}
+```
 
-兼容模式下：
+像 yunwu 这类兼容网关，通常需要设置 `XAI_COMPAT_MODE=true`。
 
-- 是否真的搜索、怎么搜索，由中转站决定
-- `--allowed-domains`、`--allowed-handles`、`--from-date` 这类 tool 参数不会下传；如果传了，CLI 会打印 warning
+## 服务选择建议
 
-## 常用命令
+推荐顺序：
 
-```bash
-grok-search "现在 X 上大家都在怎么讨论 xAI？"
-```
+1. 优先使用 xAI 官方服务。这是 `web_search` 和 `x_search` 最直接、最稳定的路径。
+2. 如果不直连 xAI，优先用 OpenRouter。这是这里最稳的非官方选项。
+3. 第三方兼容网关，例如 yunwu，更适合作为兼容兜底。很多代理站只暴露 `/chat/completions`，是否真的能搜索，取决于站点是否在内部为你开启了 web search。
 
-```bash
-grok-search "有人说 xAI 今天开源了某个模型，这是真的吗？"
-```
+推荐模型：
 
-```bash
-grok-search "找最新的 browser-use agents 相关 arXiv 论文和 GitHub 项目"
-```
+| 服务商 | 推荐模型 | 说明 |
+| --- | --- | --- |
+| xAI 官方 | `grok-4-1-fast-non-reasoning` | 这是当前 CLI 的默认模型，也是 `web_search` 和 `x_search` 支持最完整的路径 |
+| OpenRouter | `x-ai/grok-4.1-fast` | 通过 OpenRouter 接入时，优先用这个 |
+| 其他兼容网关，例如 yunwu | 以网关实际支持的 model id 为准 | 比如 yunwu 示例里使用 `grok-4-fast` |
 
-```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
-```
+### xAI 官方
 
-```bash
-grok-search "latest xAI updates" --json
-```
+直接连接 xAI 官方服务时使用。
+
+- 同时支持 Web Search 和 X Search
+- 支持网页域名过滤、X 账号过滤、日期过滤，以及图片或视频理解选项
+- 这是能力最完整的模式
+
+### OpenRouter
+
+当 `XAI_BASE_URL` 指向 `openrouter.ai` 时使用。
+
+- 支持通过 OpenRouter 的服务端搜索工具进行网页搜索
+- 只支持网页域名过滤
+- **不支持**配置 X 专属配置，例如账号、日期、以及图片或视频理解选项
+
+### 其他兼容网关
+
+当你通过其他 OpenAI-compatible 网关接入时使用。
+
+- 使用网关提供的兼容调用路径
+- 是否真的搜索、怎么搜索，由中转站决定
+- 不支持所有搜索高级配置
+
+## 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 +235,7 @@ grok-search --help
 本地如果要走 `.env`，`pnpm dev` 已经默认走 `dotenvx`：
 
 ```bash
+# 开发时通过 dotenvx 运行 TypeScript 入口
 pnpm install
 pnpm dev "latest xAI updates" --verbose
 ```