Grok CLI
A terminal coding agent for the Grok API with search, sub-agents, and automation workflows.
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.