Grok CLI
A terminal coding agent for the Grok API with search, sub-agents, and automation workflows.
- Source repo
- superagent-ai/grok-cli
- Stars
- ★ 3.5k
- Last updated
- 5mo ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specific
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer using xAI's Grok API wants a terminal agent to inspect package.json, fix a failing test, or refactor a named part of a repository.
- Not a fit if
- Teams that need multi-provider or local models instead of xAI's Grok API
- Developers on Intel Macs or Linux who need sandboxed command execution
- Source review
- 53/100 · Major gaps
What does this agent do, and when should you use it?
Grok CLI is an interactive terminal coding agent built with Bun and OpenTUI that calls xAI's Grok API. It supports both an interactive TUI and one-shot headless work through --prompt for scripts, CI, and automation. Conversations persist across runs through --session, while --format json emits newline-delimited, step-level events. The project also documents default sub-agents, MCP server configuration, Telegram remote control, image and short-video generation, and a Shuru sandbox for Apple Silicon Macs. It fits developers already using the Grok API who want an agent to operate from a local project directory through a CLI workflow.
When you run grok or grok --prompt, the CLI sends the task to its configured Grok API and runs its coding-agent workflow in the selected project directory. It exposes search_x and search_web for live X-post and web lookup, supports foreground task delegation and read-only background delegate investigations, and includes a computer sub-agent backed by agent-desktop for macOS actions such as computer_snapshot, computer_click, computer_type, and computer_scroll. Sessions can be resumed with --session latest, and headless --format json produces events including step_start, text, tool_use, step_finish, and error. generate_image and generate_video create or edit media in regular chat sessions and save output under .grok/generated-media/ by default. With /verify or --verify, it inspects, builds, tests, and launches an app, then performs sandboxed browser smoke checks and produces a verification report with screenshots and video evidence.
- A developer using xAI's Grok API wants a terminal agent to inspect package.json, fix a failing test, or refactor a named part of a repository.
- A CI or scheduled-job maintainer needs a one-shot task through grok --prompt and can use --batch-api when delayed results are acceptable.
- An engineer researching a coding problem needs live X posts and web documentation through search_x and search_web during an agent session.
- A macOS developer needs to inspect and operate the host desktop through accessibility snapshots and ref-based actions from the computer sub-agent.
- A developer wants to keep a local CLI session running while sending text or voice requests from a paired Telegram bot.
How do you install or deploy this agent?
Obtain a Grok API key. Install with curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash, or, with Bun already on PATH, run bun add -g grok-dev. Then set export GROK_API_KEY=your_key_here, or save the key with grok -k your_key_here. Interactive use requires a modern terminal emulator; the documented recommendations are WezTerm, Alacritty, Ghostty, and Kitty.
How do you use this agent?
Run grok in a project directory to start the interactive agent, or use grok -d /path/to/your/repo to select one. For a one-shot task, run grok --prompt "run the test suite and summarize failures"; for machine-readable output, run grok --prompt "summarize the repo state" --format json. Resume the latest saved session with grok --session latest, and run grok --verify to verify an application. Configure MCP servers from /mcps in the TUI or through mcpServers in .grok/settings.json.
What are this agent's strengths and limitations?
- Purpose-built for the Grok API and includes grok models for the documented model menu and pricing hints.
- Combines an OpenTUI session, --prompt headless execution, session recovery, and newline-delimited JSON events for local and automated workflows.
- Enables foreground task sub-agents and read-only background delegate investigations by default, with configurable custom sub-agents in ~/.grok/user-settings.json.
- Documents concrete extensions including search_x, search_web, media generation, Telegram pairing, and MCP configuration.
- Its core operation depends on xAI's Grok API and a valid GROK_API_KEY; no multi-provider model path is documented.
- Interactive use depends on a modern terminal emulator, with WezTerm, Alacritty, Ghostty, and Kitty specifically documented as recommended choices.
- The computer sub-agent relies on agent-desktop, currently targets macOS, and requires Accessibility permission for the terminal application.
- The Shuru sandbox requires macOS 14+ on Apple Silicon; Intel Macs and Linux cannot use sandbox mode.
- Telegram control requires creating and safeguarding a bot token, and the CLI process must remain running for long polling.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Grok CLI This agent | 53 · Major gaps | CLIFree + model costs | ★ 3.5k | 5mo ago | TypeScript | — |
| Maki Coding Agent | 67 · Some gaps | CLIFree + model costs | ★ 1.4k | 1d ago | Rust | OpenAI API · Claude API |
| Keen Code | 62 · Some gaps | — | ★ 90 | today | Go | ChatGPT · OpenAI API · Claude API |
| Alysis Code | 72 · Some gaps | CLIFreemium | ★ 213 | 1d ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence shows sandbox options, a first-workspace mode prompt, Telegram pairing approval, API-key setup guidance, and uninstall/dry-run options, so ordinary-use confirmation and recovery are reasonably addressed. Deductions: host mode, shell hooks, desktop automation, MCP, and sub-agents can exercise broad permissions; keys are called passwords, yet examples permit command-line and user-settings storage without showing encryption or access controls; details on network search, transcription, remote control, and dependency-audit coverage are limited. The README clearly disclaims xAI affiliation, and package metadata supplies an author field, but publisher identity is unverified.
README, package metadata, and AGENTS.md broadly agree on Bun, builds, and common commands, with guidance for missing API keys, terminal compatibility, and sandbox platform limits. Deductions: AGENTS.md reports a broken lint setup and a dev-mode runtime issue, and its CI-check claim is not fully corroborated by the README badges and scripts; the product also relies on many external APIs, packages, and desktop-native components without availability guarantees in the supplied material.
Documentation covers interactive and headless use, scripts/CI, session continuation, scheduling, media generation, search, remote control, and desktop automation, while stating macOS Apple Silicon sandbox and macOS desktop-automation limits. Deductions: several capabilities require external APIs, permissions, a running process, or a specific terminal; the sample does not fully explain capability differences or fallback behavior across modes.
The README is organized around installation, operation, configuration, features, and troubleshooting, with many command examples and common issues; package and CLI names and version metadata are identifiable. Deductions: the MIT license has placeholder copyright year and holder; no actual changelog is included in the supplied material; maintenance responsibility is implied mainly by repository/package metadata, without a clear team or response commitment.
Headless text and JSONL output, saved sessions, tool calls, and locally persisted generated media support downstream scripting and reuse; search, sub-agents, and verification offer clear coding-workflow value. Deductions: usefulness is primarily asserted in the README, with no execution evidence in this static review; Batch API delay, API cost, tool-round limits, and ongoing runtime costs are only partly described and not quantified.
The README ties installation, configuration, and feature claims to concrete commands and settings, while AGENTS.md gives specific locations and symptoms for known development issues. Deductions: many product claims are not matched by implementation or independent corroboration in the supplied source sample; this review did not execute the project, and the CI badge alone cannot establish behavior at this revision.
- Before allowing host filesystem, network, or desktop access, review sandbox mode, hooks, MCP, and sub-agent configuration; treat the Telegram bot token and Grok API key as credentials.
- The README says sandboxing is limited to macOS Apple Silicon and desktop automation targets macOS; AGENTS.md also reports dev-mode and lint issues.
- The MIT license retains placeholder copyright year and holder fields; the supplied material includes no changelog or maintenance response commitment.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/grok-cli)<a href="https://followagents.com/en/agents/grok-cli"><img src="https://followagents.com/badge/grok-cli.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * feat: add recaps toggle by @homanp in https://github.com/superagent-ai/grok-cli/pull/311 * feat: prompt for workspace sandbox trust by @zxyasfas in https://github.com/superagent-ai/grok-cli/pull/291 New Contributors * @zxyasfas made their first contribution in https://github.com/superagent-ai/grok-cli/pull/291 Full Changelog: https://github.com/superagent-ai/grok-cli/compare/[email protected]@1.1.7 What's Changed * feat: add recaps toggle by @homanp in https://github.com/superagent-ai/grok-cli/pull/311 …View on GitHub ↗ -
Release notes excerpt
What's Changed * chore(release): add sigstore build-provenance attestations by @veetihietasalo in https://github.com/superagent-ai/grok-cli/pull/271 * docs: update CHANGELOG from merged PRs by @homanp in https://github.com/superagent-ai/grok-cli/pull/275 * docs: add troubleshooting section with common issues and solutions by @meichuanyi in https://github.com/superagent-ai/grok-cli/pull/277 * docs: add trademark disclaimer and remove brand-confusing language by @alanzabihi in https://github.com/superagent-ai/grok-cli/pull/281 …View on GitHub ↗ -
Release notes excerpt
What's Changed * feat: replace whisper.cpp with Grok STT for Telegram audio (#265) by @homanp in https://github.com/superagent-ai/grok-cli/pull/266 * fix(release): mark RC tags as GitHub prereleases by @veetihietasalo in https://github.com/superagent-ai/grok-cli/pull/268 * chore(install): warn when auto-resolving to a pre-release version by @veetihietasalo in https://github.com/superagent-ai/grok-cli/pull/269 New Contributors * @veetihietasalo made their first contribution in https://github.com/superagent-ai/grok-cli/pull/268 …View on GitHub ↗
FAQ
Does it require a paid service?
Can I use it in CI?
Where does sandbox mode work?
What permissions does desktop automation need?
What does headless JSON output look like?
Thanks — we use this to improve the page.