grok-cli

Grok CLI 技能

此技能会将用户的 Grok / xAI 请求转化为确定性的 grok-cli 工作流。它以技能为先。在支持的发布平台上，优先使用 GitHub Release 预构建二进制文件，而不是从源代码编译。目前，macOS Apple Silicon 使用维护者上传的发布压缩包，Windows x64 使用 GitHub Actions 构建的发布 zip，而 macOS Intel / Linux 则优先通过 Cargo 从源代码构建。

仓库：

https://github.com/Moore-developers/grok-cli

核心工作流

1. 确认用户想要使用的 Grok 功能。
2. 构造命令时，保留用户的原始提示词、查询、文本、文件路径、URL 和输出指令。
3. 对于自动化、解析和可靠的错误处理，优先使用显式标志和 --json。
4. 快速路径：如果 grok-cli 可用，直接运行用户请求的 grok-cli 命令。对于常规的 chat、search、usage、媒体或音频命令，不要预先运行 status、state、登录检查、刷新检查、权限检查或功能探测。
5. 如果命令成功，按照下文的输出模式约定呈现结果。
6. 如果命令失败，检查实际的 shell 错误或 JSON 错误封装，并且只执行相应的恢复操作。
7. 恢复操作成功后，原样重试用户的原始命令，只对恢复后的环境所必需的部分进行机械性修正。
8. 如果重试失败，返回原始错误代码和消息，并附上最低限度的可执行说明。

处理安装、登录、刷新或权限问题时，请始终牢记用户的原始任务。这些是实际失败后的恢复步骤，而不是预先检查工作。

输出模式约定

默认输出模式为无损、便于阅读的呈现：解析 JSON 封装，提取特定命令的主要字段，并按原样显示其值。只有用户明确要求原始 JSON 时，才返回完整的原始 JSON。

宿主助手是 Grok 结果的呈现器，默认不是第二个编辑器。除非用户明确要求宿主助手翻译、总结、重组、改写、格式化或分析，否则保留用户的请求和 Grok 的回复。

输入处理：

• 将用户的实质性提示词、查询、文本、URL、文件路径和所要求的输出格式完全按原样传递给 grok-cli。
• 发送给 Grok 之前，不要翻译、总结、扩展、缩短、清理、规范化、改进或重新诠释用户的措辞。
• 除非用户明确提供，否则不要向 Grok 提示词中添加隐藏指令、额外上下文、偏好结构、安全措辞、风格规则或示例。
• 只进行 shell 或 CLI 所需的机械性更改，例如加引号、转义、选择正确的标志、添加用户要求的显式日期标志，或解析本地路径。
• 设置探测、身份验证检查和权限检查与用户的原始任务相互独立。绝不要将它们的提示词或输出混入用户的 Grok 请求。

输出处理：

• 对于文本命令，呈现 Grok 生成的确切文本值：chat --json 的 data.output_text、search --json 的 data.answer，以及 stt --json 的 data.transcript。
• 不要总结、转述、翻译、重排、删减、润色 Markdown、添加标题、添加项目符号、纠正语法、将引文合并到正文中，或以其他方式改写 Grok 的文本。
• 在聊天界面允许的范围内，保留 Grok 的空白字符、换行、代码围栏、引文、编号和措辞。
• 对于媒体命令，返回 JSON 字段中的确切生成文件路径、URL、数据 URL、请求 ID、媒体标签或句柄。不要重命名或添加评论。
• 如果用户要求原始 CLI 输出或原始 JSON，则完整返回 stdout/stderr 内容，仅进行安全显示所需的最少围栏处理。
• 如果用户明确要求宿主助手总结、翻译、改写、提取、格式化、比较、分类或重组 Grok 的输出，则进入转换模式，并明确说明结果是转换后的内容，而非 Grok 的原文。
• 如果进行了恢复，仅在 Grok 结果之后用简短的独立说明提及。不要将恢复说明插入 Grok 结果中。
• 如果命令失败，则返回原始错误代码和错误消息。仅针对身份验证、权限或命令格式阻塞问题，添加最低限度的可操作恢复说明。

快速路径与恢复

常规用户任务应优先直接执行：

1. 构建用户的原始命令，例如 grok-cli search --json --query "..."。
2. 直接运行该命令。
3. 如果成功，则呈现结果。
4. 如果失败，则根据实际错误进行恢复，然后重试一次原始命令。

在收到实际用户请求之前，不要运行就绪探测，例如 grok-cli search --json --query "Grok" 或 grok-cli chat --json --prompt "Reply with exactly: ok"。用户要求搜索时，应先执行实际搜索。

结构化恢复：

• 如果 JSON 错误包含 error.recovery_action，则以此为唯一依据。不要将 code、message、relogin_required 或 entitlement_denied 重新解释为其他操作。
• refresh_then_retry：运行 grok-cli refresh --json，然后将原始命令重试一次。
• login_then_retry：运行 grok-cli login，然后将原始命令重试一次。
• wait_then_retry：如果存在 error.retry_after_seconds，则等待相应时长，然后将原始命令重试一次。如果没有提供重试等待时间，则返回速率限制消息。
• fix_args_then_retry：如果缺失或不兼容的参数很明确，则修正命令格式，然后重试一次。
• stop_billing：停止操作，并说明必须在 CLI 外修复官方账户的账单、余额、额度或消费上限。
• stop_quota：停止操作，并说明配额或使用限额已用尽。
• stop_rate_limit：停止操作，并说明上游速率限制未提供重试时间。
• stop_entitlement：停止操作，并说明该账户或订阅无法使用此功能。
• stop_unknown 或 none：返回原始错误代码和消息，并附上最简要的必要说明。

旧版 grok-cli 没有 recovery_action 时的备用恢复方法：

• Shell 无法找到 grok-cli：安装它，验证 grok-cli --version 和 grok-cli --help，然后重试原始命令。
• Shell 提示缺少子命令：修复或升级安装，验证 grok-cli --help，然后重试原始命令。
• 凭证问题优先于权限措辞。如果错误代码或消息包含 auth_missing、无效身份验证、凭证验证失败（例如 bad-credentials）、The OAuth2 access token could not be validated、令牌过期、令牌失效或 auth_expired，则先运行 grok-cli refresh --json，然后重试原始命令。即使同一错误信息也包含 entitlement_denied: true 或 xai_oauth_tier_denied，也要这样做。
• 如果刷新失败是因为本地身份验证状态缺失、无法通过刷新恢复会话，或 relogin_required 为 true，则运行 grok-cli login，然后重试原始命令。
• 原始命令返回的 JSON 错误 state_file_missing、auth_relogin_required 或 relogin_required: true 表示刷新不太可能有帮助；运行 grok-cli login，然后重试原始命令。
• 如果 status --json 返回 access_token_expiring，仅当用户明确要求查看状态或诊断信息时才刷新。不要为了发现此情况而在执行常规任务前运行 status。
• billing_required、payment_required、insufficient funds、insufficient balance、credits 或 spend cap：停止操作，并说明必须在 CLI 外修复官方账户的账单或余额。
• quota_exhausted、insufficient_quota、quota exceeded 或 usage limit：停止操作，并说明配额已用尽，除非错误提供了重试时间。
• rate_limited 或 rate limit：仅当错误提供了重试等待时间时才重试；否则停止操作。
• 如果只有 entitlement_denied 或 xai_oauth_tier_denied，且没有任何凭证验证相关措辞，则说明该账户或订阅无法使用此功能。除非错误也明确要求重新登录，否则不要重试、重新安装、刷新或重新登录。
• invalid_args：如果可以明确正确的命令格式，则修正后重试一次。如果缺少必要信息，则向用户询问缺少的输入。

恢复后，重试用户的原始命令，而不是探测命令。准确保留原始提示词或查询内容。

用户可以通过此技能执行的操作

用户应能将此技能作为 grok-cli 的主要接口。将请求路由到以下受支持的功能：

• 使用 chat 进行常规 Grok 推理和写作
• 使用 search 搜索 X / Twitter
• 使用 image 生成图像
• 使用 image-edit 编辑图像
• 使用 video 生成视频
• 使用 video-edit 编辑视频
• 使用 video-extend 延长视频
• 使用 tts 进行文本转语音
• 使用 stt 批量进行语音转文本
• 使用 stt-stream 实验性地流式进行语音转文本
• OAuth 安装 / 登录 / 刷新 / 状态 / 登出 / 状态数据
• 使用 usage 检查本地用量

重要支持规则：

• video 支持文本转视频、--image-url、本地 --image、--reference-image-url 和本地 --reference-image。
• video-edit 同时支持 --video-url 和本地 --video。
• video-extend 仅支持 --video-url。
• 不要提供 video-extend --video <PATH>。实际验证表明，本地 MP4 输入可以传到 xAI，但延长视频的生成最终会遇到上游内部错误。用户应先上传视频，然后使用 --video-url。
• image-edit --image 接受本地路径和远程 URL。
• stt 支持本地文件和远程 --url。
• stt-stream 具有实验性质；除非用户明确需要流式处理，否则优先使用 stt。

安装检查

首先检查命令是否存在：

command -v grok-cli
grok-cli --version
grok-cli --help

仅检查版本还不够。较旧的预发布版本可能会报告有效版本号，但缺少较新的命令。请确认顶层帮助信息包含以下必需命令：

image-edit
video-edit
video-extend
stt-stream
update

如果缺少 grok-cli，或缺少任何必需命令，请先识别平台，然后按以下顺序选择安装方式：

• macOS Apple Silicon：优先使用 GitHub Release 资源 grok-cli-macos-aarch64-apple-darwin.tar.gz。
• Windows x64：优先使用 GitHub Release 资源 grok-cli-windows-x86_64-pc-windows-msvc.zip。
• macOS Intel 和 Linux：使用 Cargo 源码安装。
• 如果受支持平台的 Release 资源意外缺失，请明确说明，不要在产品平台上悄悄改用 Cargo。
• 仅在用户明确要求构建源码，或平台优先使用源码时，才使用 Cargo。

仅当平台优先使用源码，或用户明确想要构建源码时，才检查 Cargo 是否可用：

command -v cargo

源码安装时，还要检查当前使用的编译器版本：

rustc --version

grok-cli 源码安装要求 Rust 1.88 或更高版本，因为该 crate 使用 edition 2024，并声明了 rust-version = "1.88"。CI 和本地开发通过 rust-toolchain.toml 固定使用 Rust 1.92.0。

用户的平台受支持时，默认使用 GitHub Release 二进制文件：

• macOS Apple Silicon：grok-cli-macos-aarch64-apple-darwin.tar.gz
• Windows x64：grok-cli-windows-x86_64-pc-windows-msvc.zip

如果 macOS Intel 或 Linux 上缺少 Cargo，不要编造二进制安装方式；请告知用户需要先安装 Rust/Cargo，并引导他们使用 rustup 安装 Rust。

如果 rustc --version 显示版本低于 1.88，请停止操作并说明确切要求，不要笼统地让用户“升级 Rust”。请说明 grok-cli 源码安装要求 Rust 1.88+，且仓库当前使用的工具链版本是 1.92.0。然后建议用户选择以下方式之一：

• 在 macOS Apple Silicon 或 Windows x64 上使用 Release 二进制文件，或
• 在优先使用源码的平台上运行 rustup update，然后重试源码安装。

安装 Release 二进制文件时：

1. 确认平台与资源名称完全匹配。
2. 从最新的 GitHub Release 下载资源及其对应的 .sha256 文件。
3. 尽可能验证校验和。
4. 解压二进制文件。
5. 将 grok-cli 或 grok-cli.exe 放入已在 PATH 中的目录；如果没有合适的目录，则使用 ~/.local/bin，将其临时添加到当前 shell 的 PATH，并告知用户如何永久添加。
6. 如果 command -v grok-cli 仍然失败，但 ~/.local/bin/grok-cli 存在且可执行，请将其视为 PATH 配置问题，而不是安装失败。继续临时导出 PATH="$HOME/.local/bin:$PATH"，或直接使用 ~/.local/bin/grok-cli 进行验证。
7. 运行 grok-cli --version 和 grok-cli --help。
8. 重试原始 Grok 任务。如果该任务报告身份验证问题，请按照下文的 OAuth 处理方式操作。

如果选择使用 Cargo，并且用户要求安装最新版本，请从仓库最新状态安装：

cargo install --git https://github.com/Moore-developers/grok-cli.git --locked --force

指定公开版本时：

cargo install --git https://github.com/Moore-developers/grok-cli.git --tag v0.1.6 --locked --force

安装后，验证：

grok-cli --version
grok-cli --help
grok-cli update --check --json

仅当用户明确要求升级 CLI 时，才使用 grok-cli update。用户要求禁用被动更新提示时，使用 grok-cli update --no-update-check；用户要求重新启用提示时，使用 grok-cli update --enable-update-check。执行常规 Grok 任务前不要运行更新检查；CLI 在 JSON 和原始流自动化输出中会跳过被动提示。

如果因为缺少命令而重新安装，请在验证后重新运行用户的原始任务。不要在安装完成后就停止。

OAuth 处理

日常调用 Grok 前，不要检查 OAuth 状态。先运行用户的实际命令，只有在报告身份验证问题时才进行恢复。

对于当前 grok-cli JSON 错误，请按照 error.recovery_action 处理：

• refresh_then_retry：运行 grok-cli refresh --json，然后将原命令重试一次。
• login_then_retry：运行 grok-cli login，然后将原命令重试一次。
• stop_billing、stop_quota、stop_rate_limit 或 stop_entitlement：停止并说明阻碍；不要刷新、重新登录、重新安装或运行探测命令。

对于没有 recovery_action 的旧版 grok-cli JSON 错误，请使用上述备用恢复映射。如果重试仍然失败，请清楚说明返回的结构化错误；仅当错误指出需要重新登录时，才要求登录。

命令路由

默认使用明确的标志和 --json，以确保自动化可靠。

使用 chat 进行通用的 Grok 推理或问答：

grok-cli chat --json --prompt "Summarize this topic"

使用 search 搜索 X / Twitter / 社交讨论：

grok-cli search --json --query "What are builders saying about Grok today?"

对于 X 搜索任务：

• 如果用户要求搜索今天的内容、近期讨论或指定时间范围内的内容，请加入相关的日期标志。
• 按照用户原样传递搜索查询文本。
• 运行命令后，原样返回 Grok 返回的 data.answer。
• 显示引用时，准确保留 data.citations 和 data.inline_citations。
• 除非用户明确要求你进行分析，否则不要添加主机助手对结果是否充分、情绪倾向或含义的结论。
• 如果命令本身报告结果稀少或缺失，请原样传递该消息，不要另行总结。

使用 image 生成图像：

grok-cli image --json --prompt "A cinematic skyline at sunrise"

使用 image-edit 编辑图像：

grok-cli image-edit --json --image ./source.png --prompt "Make it cinematic"

使用 video 生成视频：

grok-cli video --json --prompt "Animate a futuristic skyline" --duration 8

使用 video-edit 编辑现有视频：

grok-cli video-edit --json --video-url https://example.com/source.mp4 --prompt "Make it cinematic"

使用 video-extend 延长现有视频：

grok-cli video-extend --json --video-url https://example.com/source.mp4 --prompt "Continue the camera move" --duration 6

使用 tts 进行文本转语音：

grok-cli tts --json --text "Hello from Grok"

使用 stt 批量进行语音转文本：

grok-cli stt --json --file ./sample.wav

使用 usage 查看本地使用统计：

grok-cli usage --json

常用参数速查表

本页介绍常用选项和一些典型值。如果用户询问罕见标志、确切的取值范围或复杂的组合规则，请停止查阅本页，转而打开下方对应的参考文件，不要试图把所有内容都塞进主 SKILL。

• login：当机器无法完成常规浏览器回调时，使用 --no-browser、--manual-paste、--timeout 300 和 --port 8787。
• status、refresh、logout、state：当用户需要使用其他本地 OAuth 状态文件时，使用 --auth-file <PATH>。
• model：使用 --model grok-4.5 或 --model grok-4.6 为 chat 和 search 设置共享的默认文本模型；不支持其他文本模型。
• usage：使用 --session-db <PATH> 和 --session-id <ID> 指定本地使用记录。
• chat：使用 --prompt 或位置参数形式的提示词、--system、--model、--no-web-search、--with-x-search、--allowed-domain example.com、--stream、--no-stream、--raw-stream 和 --timeout 3600。
• search：使用 --query 或位置参数形式的查询、--model、--allowed-x-handle xAI、--from-date 2026-05-01、--to-date 2026-05-21、--stream、--no-stream、--raw-stream 和 --timeout 3600。
• image：使用 --count 1-10、--response-format url|b64_json、--output-file <PATH>、--output-dir <PATH>、--aspect-ratio 1:1 和 --resolution 1k。
• image-edit：最多重复使用 3 次 --image；在本地写入时，使用 --output-file <PATH> 和 --response-format b64_json。
• video：使用 --image ./source.png、--reference-image ./a.png、--duration 8、--aspect-ratio 16:9 和 --resolution 720p。
• video-edit：使用 --video ./source.mp4 或 --video-url https://...。
• video-extend：使用 --video-url https://... 和 --duration 6。
• tts：使用 --list-voices、--text、--voice-id ara、--language en、--output ./out.mp3 和 --output-format mp3。
• stt：使用 --file ./sample.wav、--url、--language auto、--format true、--diarize、--keyterm Grok 和 --filler-words。
• stt-stream：使用 --file ./sample.wav、--interim-results、--language auto 和 --sample-rate 16000。

参考文件索引

如果用户需要了解标志的确切行为、罕见组合或完整参数范围，请查阅对应的参考文件：

• references/install-and-auth.md：安装、状态、登录、刷新、登出、状态信息和 auth-file 处理。
• references/commands-basic.md：chat、search、model、usage 和文本命令筛选器。
• references/commands-media.md：image、image-edit、video、video-edit、video-extend、TTS 和 STT 的常见用法。
• references/commands-advanced.md：确切取值、罕见标志、组合规则和边缘情况。
• references/errors.md：JSON 错误、身份验证恢复和权益处理。
• references/outputs.md：要读取的稳定 JSON 字段。

当用户提供本地媒体路径时：

• image-edit --image ./file.png：支持
• video --image ./file.png：支持
• video --reference-image ./file.png：支持
• video-edit --video ./file.mp4：支持
• video-extend --video ./file.mp4：当前公开 skill 范围不支持；请改用远程 URL 工作流

技能测试提示词

使用这些提示词验证 Codex 或 Claude Code 是否正确路由到此技能，并选择预期的 grok-cli 命令形式。如需查看完整矩阵（包含所有公开功能和本地文件支持），请参阅：

• docs/project/skill-validation-cases.md

最低限度的路由和原样传递检查：

• 用 Grok 总结一下最近关于 Rust CLI 设计的讨论，返回结构化结果 预期路由：grok-cli chat --json --prompt ...；提示词文本必须保持不变。
• 搜索一下 X 上大家今天怎么评价 Grok CLI 预期路由：grok-cli search --json --query ...；查询文本必须保持不变。
• 生成一张 1:1 的极简终端图标，保存到本地 预期路由：grok-cli image --json --prompt ... --aspect-ratio 1:1 --output-file ...
• 把这张图片改得更像命令行工具封面：./source.png 预期路由：grok-cli image-edit --json --image ./source.png --prompt ...
• 用这张本地图片做一个短视频：./source.png 预期路由：grok-cli video --json --prompt ... --image ./source.png
• 编辑这个本地视频，让画面更有电影感：./source.mp4 预期路由：grok-cli video-edit --json --video ./source.mp4 --prompt ...
• 把这个视频再延长两秒：https://example.com/source.mp4 预期路由：grok-cli video-extend --json --video-url https://example.com/source.mp4 --duration 2 --prompt ...
• 把这段文字转成 ara 声音的 mp3 并保存 预期路由：grok-cli tts --json --text ... --voice-id ara --output ... --output-format mp3
• 转写这个音频，并保留关键词 Grok 和 CLI：./sample.wav 预期路由：grok-cli stt --json --file ./sample.wav --keyterm Grok --keyterm CLI ...

负向路由检查：

• 如果用户要求直接延长本地视频文件，技能不得臆造 video-extend --video ./source.mp4。
• 相反，技能应说明 video-extend 目前需要远程 URL，并请求提供上传 URL，或协助生成上传 URL 工作流。

错误处理

从标准封装中读取 JSON 错误：

{
  "ok": false,
  "command": "chat",
  "error": {
    "code": "auth_missing",
    "message": "...",
    "relogin_required": false,
    "entitlement_denied": false,
    "category": "auth_refreshable",
    "recovery_action": "refresh_then_retry",
    "retryable": true,
    "retry_after_seconds": null,
    "billing_required": false,
    "quota_exhausted": false,
    "rate_limited": false
  }
}

重要处理规则：

• 优先使用 error.recovery_action，而不是其他任何字段。
• 如果本地二进制版本较旧，导致 recovery_action 缺失，则使用上述备用恢复规则。
• 计费、配额和纯权益限制不应触发刷新、登录或反复重新安装。
• 如果命令返回参数无效，应修正命令形式，而不是让用户排查 CLI 语法。

面向用户的输出

默认采用无损、易读的呈现方式：解析 JSON 封装，提取特定命令的主要字段，并按原样显示其值。然后简要说明执行过的恢复操作，例如安装 grok-cli、刷新凭据或完成 OAuth。

对于文本命令，原样复制 data.output_text、data.answer 或 data.transcript。对于媒体命令，报告返回的确切文件路径、URL、请求 ID、媒体标签或生成的媒体句柄。只有用户要求原始 JSON 时才返回原始 JSON；如有此要求，须原样返回 JSON。