# Use Grok

> Delegate tasks to the Grok Build CLI (`grok`) — Q&A, code review, adversarial critique, task delegation, image generation/editing, and X (Twitter) search. Trigger whenever the user mentions Grok in any form — "用 grok xxx", "让 grok xxx", "grok review", "grok ask", "grok run", "grok critique", "grok 生图", "用 grok 画一张图", "grok image", "grok imagine", "grok 搜 X", "grok x-search", "grok 搜推特", "search X with grok", or any other request that involves Grok (including generating or editing images, or searching X/Twitter with Grok). When triggered, route the request to the appropriate use-grok subcommand.

- Skill: `xiaoz-0218/use-grok` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add xiaoz-0218/use-grok`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaoz-0218/use-grok/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: XiaoZ-0218 (https://skillmd.com/u/xiaoz-0218)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiaoz-0218/use-grok

---


# use-grok

`use-grok` is a CLI bridge to the Grok Build CLI. Every command accepts `--json` for machine parsing; exit code 0 means success, 1 means error or failed/cancelled run, 2 means unknown command.

## Setup

Run `use-grok check --json` first. It verifies Node, the `grok` binary (override with the `GROK_BINARY` env var), and authentication. If `ready` is `false`, tell the user to install or authenticate `grok` — do not retry other commands.

## Commands

- `use-grok ask "<prompt>"` — single-turn Q&A.
- `use-grok review [--scope auto|working-tree|branch] [--base <ref>]` — read-only code review. Auto scope reviews the working tree (staged, unstaged, and untracked changes) when it is dirty, otherwise the current branch against the default base branch.
- `use-grok critique [focus...]` — adversarial ship/no-ship critique with structured findings (severity, file and line range, confidence, recommendation). Best before merging or after a large change. Extra positional words become the focus topic.
- `use-grok run "<prompt>"` — delegate a task. Read-only by default (plan permission mode + read-only sandbox). Only pass `--write` when the user explicitly asked Grok to modify files.
- `use-grok image "<prompt>" [--out <path>] [--aspect-ratio <ratio>] [--ref <image>...]` — generate an image with Grok's `image_gen` tool, or edit existing images with `image_edit` when `--ref` is given. The result is saved to `--out` (default `./grok-image-<timestamp>.png`). Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `auto`. Unlike `run`, this command always permits Grok to write files because the image tools save output to disk.
- `use-grok x-search "<query>" [--kind keyword|semantic|user|thread] [--from <handle>] [--mode latest|top] [--limit <n>]` — search X (Twitter) via Grok's backend XSearch. `--kind` selects `x_keyword_search` (default), `x_semantic_search`, `x_user_search`, or `x_thread_fetch`. Post hits use url/handle/text/date with full post text; user hits use url/handle/name/bio. `--from` and `--mode` apply to keyword/semantic only. `--mode` defaults to `latest`; `--limit` defaults to `10`. For `--kind thread`, the query is a post URL or status id. Do not use `ask` or `run` for X search — this command forces X search and forbids falling back to `web_search`.
- `use-grok runs [run-id] [--wait]`, `use-grok show [run-id]`, `use-grok stop [run-id]` — list, wait for, inspect, and stop background runs.

## Usage patterns

- Always pass `--json` when you need to act on the result, and parse stdout.
- Run from the repository root (or pass `--cwd <dir>`) so review scope and per-workspace run state resolve to the right place.
- For long operations use `--background`, then poll with `use-grok runs <run-id> --wait --json`, and read the output with `use-grok show <run-id> --json`. `review`, `critique`, and `image` also accept `--background --wait` to block until the result is ready in one call.
- Image generation: pick `--aspect-ratio` to match the use case (`9:16` phone/story, `16:9` banner, `1:1` avatar/icon). To keep a character or style consistent across images, generate a base image first, then pass it via `--ref` for every variation. The CLI fails the command if the `--out` file is missing after the run; on success, still confirm the image content matches the request before showing or embedding it.
- X search: pass `--json` and read `output`. Use `--kind semantic` for natural-language search, `--kind user` to find accounts, `--kind thread` with a post URL to fetch a thread. Use `--from` for an account and `--mode top` for popular posts (keyword/semantic only). If the output says X search is unavailable, report that instead of retrying with `ask` or web search.
- A stopped run is reported as `cancelled` and exits 1; a failed Grok invocation exits 1 with details on stderr.

## Safety

`review` and `critique` never modify the repository. `run` without `--write` cannot edit files either — treat `--write` as an explicit user decision, never a default. `x-search` is read-only (backend X search) but auto-approves the search tool so a headless run does not stall. `image` runs Grok with write permission (like `run --write`) and instructs it to write only the `--out` file, but that is prompt guidance, not a sandbox — treat `image` as write-capable and never point `--out` at files the user did not ask to create or overwrite. After an `image` run, the CLI verifies the `--out` file exists and fails the command if it does not.