gr

A tiny, convenient Bash wrapper for non-interactive (headless) conversations with Grok Build.

gr lets you send a prompt from the command line without launching the full TUI. All trailing arguments that aren't flags are joined together and sent as the prompt text to the grok CLI via its -p / --single headless mode.

By default, gr continues the most recent conversation/session for the current directory (session-stateful behavior). Use --new (or -N) to start a completely fresh session instead.

Why?

• Quick one-off questions or tasks from your shell or scripts
• Easy to use in pipelines, git hooks, Makefiles, etc.
• Familiar "the rest of the arguments are the message" UX (like many other AI CLIs)
• Full access to all the powerful headless flags (--yolo, sessions, JSON output, tool filtering, etc.)

Installation

The easiest way is to put gr somewhere on your $PATH. For example:

# Via the official Grok Build installation (recommended)
ln -s ~/.grok/bin/gr ~/.local/bin/gr   # or /usr/local/bin/gr, ~/bin, etc.

# Or manually from this repo
git clone .../gr.git
cd gr
chmod +x gr
cp gr ~/.local/bin/

After installation:

gr --version
gr --help

gr looks for the real grok binary in $PATH first, falling back to ~/.grok/bin/grok. You can override with GROK_BIN=/path/to/grok gr ....

Usage

gr [OPTIONS] <chat text...>

Everything after the options (the "remaining varargs") is joined with spaces and becomes the prompt sent to Grok Build.

Common Examples

# Simple prompt (continues the most recent session in this directory by default)
gr explain how git rebase works

# With YOLO mode (auto-approve all tool calls)
gr -y "review this PR and fix any obvious bugs"

# Continue explicitly (usually unnecessary — this is now the default)
gr -c "now add the tests we discussed"

# Start a completely fresh session (ignore any previous conversation)
gr --new "start a brand new task from scratch"
gr -N "another fresh session"

# Named / resumable session + JSON output (great for scripting)
gr --json -s my-feature-42 "update the design doc with the new constraints" | jq -r .text

# Pipe context into the prompt
git diff --cached | gr "write a clear conventional commit message for these changes"

# Use a specific model or limit tool use
gr -m grok-build --disallowed-tools "run_terminal_cmd,web_search" "analyze the security model of this code"

# Load prompt from a file
gr --prompt-file ./task.txt --yolo

# Stop flag parsing early
gr --yolo -- "this sentence starts with a dash - no problem"

Important Flags

Flag	Description
-y, --yolo	Auto-approve all tool executions
(default)	Continue the most recent session in this dir
-c, --continue	Explicitly continue (usually redundant now)
-N, --new, --new-session	Start a fresh new session (do not continue)
-r, --resume [ID]	Resume a specific session (or latest)
-s, --session-id <ID>	Use/create a named persistent session
-m, --model <MODEL>	Choose model (e.g. grok-build)
--json / -J	JSON or streaming JSON output
--cwd <PATH>	Run with a different working directory
--rules <TEXT>	Append extra rules to the system prompt
--allow / --deny	Permission rules (repeatable)
--tools / --disallowed-tools	Fine-grained tool allow/deny lists
--check, --self-verify	Append an automatic verification loop
--best-of-n <N>	Run the task N times in parallel and pick the best
--dry-run, -n	Show the exact grok command that would be run
--	Stop parsing flags; everything after is prompt text
-h, --help	Show full help
-v, --version	Show grok version

All other flags are passed straight through to the underlying grok binary (see grok --help for the complete list of headless options).

How It Works

gr is a small, self-contained Bash script (~260 lines). It:

1. Parses known convenience flags and a generous set of headless flags.
2. By default injects -c (continue most recent session) unless --new / -r / -s / -c is explicitly used.
3. Collects every non-flag argument (plus anything after --) into the prompt.
4. If no arguments are given and stdin is not a TTY, it reads the prompt from stdin.
5. Executes grok -p "<prompt>" [forwarded flags...] (or the equivalent when using --prompt-file etc.).
6. Uses exec so exit codes, signals, and stdin/stdout are passed through cleanly.

This means you get the full power (and safety model) of official Grok Build headless mode while enjoying a friendlier CLI for ad-hoc use.

Exit Codes

gr passes through the exit codes from grok:

• 0 — Success
• 1 — Error (auth, network, runtime, etc.)
• 130 — SIGINT (Ctrl-C)
• 143 — SIGTERM

See the official [Headless Mode documentation](https://github.com/xai-org/grok or your local docs) for details.

Contributing / Development

This repo contains the canonical source for the gr wrapper.

# Make a change
./gr --dry-run -y "do something cool"

# The script is designed to be easily auditable
# Run it through shellcheck if you have it

License

MIT (or whatever the Grok Build distribution uses). Feel free to copy the script into your own projects.

Related

• The official grok / agent CLI from xAI
• Headless / scripting mode (grok -p ...)
• Grok Build TUI and Agent Client Protocol (ACP) support

---

v0.2.0 — Session-continuing by default (-c no longer required). Added -N/--new to start a fresh session.