Grok CLI
A terminal coding agent for the Grok API with search, sub-agents, and automation workflows.
Per-dimension scores and reasoning
Evidence shows: README clearly explains API key can be provided via environment variable, .env, or user settings, and warns to treat Telegram token like a password; provides sandbox mode (--sandbox) to limit host access; Telegram pairing requires user approval; security scan workflow exists (bun pm untrusted and trufflehog). Deductions: data flow not detailed (e.g., what data is sent to xAI, Telegram, or third parties); user confirmation before all tool executions not explicit; many third-party dependencies without vulnerability mitigation details; external effects (e.g., desktop automation, network access) not fully described; rollback only mentions uninstall --keep-config, no session or change rollback.
Evidence shows: README and package.json are consistent, command examples match documentation; troubleshooting section covers common issues; CI workflow exists. Deductions: dependency availability not verified (e.g., agent-desktop native binary download may fail, README provides manual steps); error messages only partially covered, not all failure scenarios detailed.
Evidence shows: targets developers, provides interactive and headless modes, supports multiple terminals, supports macOS and Linux (sandbox only macOS 14+ Apple Silicon); capability boundaries clear (e.g., sandbox limitations, computer sub-agent macOS only); triggers clear (natural language, command flags); environment fit good (environment variables and config files). Deductions: platform-specific requirements not fully detailed (e.g., Windows support limited); not all scenarios have configuration examples.
Evidence shows: README well-structured with install, run, configuration, troubleshooting sections; install script and npm package provided; naming stable (grok command); multiple examples and FAQ; known limitations stated (e.g., sandbox macOS only); MIT license; version number exists (1.1.7). Deductions: no CHANGELOG file; maintenance responsibility unclear (author Vibe Kit, but no maintenance policy).
Evidence shows: output formats diverse (text, JSON event stream), structured output supported; unique features (e.g., Telegram remote control, media generation, verification); cost-benefit good (--batch-api reduces cost). Deductions: no performance benchmarks or user feedback; cost savings not quantified.
Evidence shows: README claims consistent with code and config (e.g., model list, features); CI and test scripts present; security scan workflow exists. Deductions: no test results or coverage; no independent verification; facts and inferences not clearly separated (e.g., 'coming soon' section).
- The tool requires API keys and Telegram tokens; handle them securely to avoid leakage.
- Sandbox mode only works on macOS 14+ Apple Silicon; not available on other platforms.
- Computer sub-agent requires macOS Accessibility permission, which may pose security risks.
- Many third-party dependencies; recommend regular security audits.
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.
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 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.