TL;DR

grok-cli (published on npm as grok-dev) is a community-built, open-source terminal coding agent that talks to xAI’s Grok API. It is not xAI’s official tool — that would be Grok Build, the 840K-line Rust harness xAI open-sourced in July. grok-cli is the scrappier, more experimental TypeScript alternative from the Superagent team, and it does a few things the official CLI does not. Highlights:

  • Telegram remote control — pair once, then drive the agent from your phone while the CLI keeps running on your machine
  • Sub-agents on by default — foreground task delegation plus background delegate for read-only deep dives
  • Built-in computer use — a computer sub-agent (via agent-desktop) that snapshots and drives your macOS desktop
  • Shuru microVM sandbox — run shell commands inside an isolated VM so the agent can’t touch your host filesystem or network (macOS 14+ Apple Silicon)
  • Live X + web search — search_x and search_web tools, so the agent isn’t stuck in a 2023 knowledge cutoff
  • Media generation — generate_image and generate_video tools inside a normal chat session
  • --verify mode — inspects, builds, boots, and browser-smoke-tests your app in a sandbox with screenshot/video evidence
  • MIT licensed, TypeScript, built on Bun + OpenTUI, installable in one curl line

If you use the Grok API and want a hackable agent with phone-driven remote control, grok-cli is worth a look. If you want the battle-tested official harness, use Grok Build. This review covers what grok-cli actually does, how to install it, honest limitations, and how it stacks up.

Quick Reference

Repositorygithub.com/superagent-ai/grok-cli
LicenseMIT
LanguageTypeScript (Bun runtime)
NPM packagegrok-dev
MaintainerSuperagent (community; not affiliated with xAI)
Installcurl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash
RequiresGrok API key from x.ai, modern terminal emulator
TUIOpenTUI (React-in-terminal)
SandboxShuru microVM (macOS 14+ Apple Silicon only)

What Is grok-cli?

grok-cli is an open-source terminal coding agent that connects to xAI’s Grok API. Conceptually it sits in the same category as Claude Code, Codex CLI, OpenCode, and Gemini CLI: a full-screen terminal UI that understands your codebase, edits files, runs shell commands, searches the web, and manages long-running tasks — but pointed at Grok models like grok-4.3 and the grok-4.20 multi-agent variants.

The important framing, because it confuses a lot of people: there are two things called “Grok” in the coding-agent world right now.

  1. Grok Build — xAI’s official agent harness, open-sourced under Apache 2.0 in mid-July 2026. It’s ~840K lines of Rust, is the code behind the real grok command, and takes no external PRs. It’s the safe, production choice.
  2. grok-cli / grok-dev — this project. Community-built, MIT-licensed, TypeScript, and explicitly not affiliated with, endorsed by, or sponsored by xAI Corp. It predates the official open-source release and carved out its own feature set.

The README is blunt about the disclaimer: “This project is community-built, open-source, and not affiliated with, endorsed by, or sponsored by xAI Corp. ‘Grok’ is a trademark of xAI Corp. This tool uses the publicly available Grok API.” Keep that in mind — you’re trusting a community maintainer, not xAI, with an agent that can edit files and run shell commands.

Installation

The fast path is a single curl command that bundles Bun for you:

curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash

If you already have Bun on your PATH, you can skip the bundled runtime:

bun add -g grok-dev

Then set your Grok API key (get one from x.ai) using any of these:

# Environment variable
export GROK_API_KEY=your_key_here

# Or persist it to user settings
grok -k your_key_here

# Or drop a .env in the project
echo "GROK_API_KEY=your_key_here" >> .env

Launch the interactive OpenTUI agent:

grok
# or point it at a specific repo
grok -d /path/to/your/repo

One quirk worth flagging up front: OpenTUI is picky about terminals. The maintainers explicitly recommend WezTerm, Alacritty, Ghostty, or Kitty. If you run it in the default macOS Terminal or an older emulator, expect flickering or rendering artifacts — the troubleshooting section of the README is basically a list of “try a different terminal” answers.

Headless Mode: The Part That Actually Matters for Automation

Interactive TUIs are nice, but the reason to care about a CLI agent is scripting. grok-cli’s headless mode is solid:

# One prompt, then exit
grok --prompt "run the test suite and summarize failures"

# Point at a project, cap the tool rounds
grok -p "refactor the auth module" --directory /path/to/project --max-tool-rounds 30

# Structured, machine-readable output
grok --prompt "summarize the repo state" --format json

# Cheap unattended runs via xAI's Batch API
grok --prompt "review the repo overnight" --batch-api

--format json emits a newline-delimited JSON event stream — step_start, text, tool_use, step_finish, error — which is exactly what you want when you’re piping the agent into CI and need to parse what it did. --batch-api routes unattended runs through xAI’s Batch API for lower cost, which is a genuinely thoughtful touch for scheduled or overnight jobs where a delayed result is fine.

Sessions persist, so grok --session latest or grok -s <session-id> picks up where you left off — useful for multi-run workflows.

The Standout Feature: Telegram Remote Control

This is grok-cli’s signature trick and the reason it keeps showing up in “what’s new” roundups. You can pair a Telegram bot and then drive the agent from your phone while the CLI process keeps running on your machine.

Setup, roughly:

  1. Create a bot with @BotFather and copy the token.
  2. Set TELEGRAM_BOT_TOKEN (or add telegram.botToken in ~/.grok/user-settings.json — the TUI’s /remote-control flow can save it for you).
  3. Start grok, open /remote-control → Telegram, then DM your bot /pair and enter the 6-character code in your terminal.
  4. The first user is approved once and remembered thereafter.

The catch: long polling lives inside the CLI process, so the terminal session has to stay running for the bot to work. It’s remote control, not a hosted service. There’s also a headless bridge (grok telegram-bridge) if you don’t want the TUI open.

A neat bonus: send a voice note in Telegram and grok-cli transcribes it via the Grok Speech-to-Text API (POST /v1/stt) before handing the text to the agent. A recent changelog entry (#265, #266) shows they removed the whisper.cpp / ffmpeg / local-model-download path in favor of the hosted STT endpoint — one fewer thing to install, at the cost of sending your audio to xAI.

Treat the bot token like a password. Anyone who can DM your bot after approval can steer an agent that edits files and runs shell commands.

Sub-Agents, Computer Use, and the Sandbox

grok-cli leans hard into agent orchestration:

  • Sub-agents are on by default. Foreground task delegation handles things like explore, general, or computer work; background delegate spins up read-only deep dives so you can parallelize. You can define custom named sub-agents in ~/.grok/user-settings.json:
{
  "subAgents": [
    {
      "name": "security-review",
      "model": "grok-4.3",
      "instruction": "Prioritize security implications and suggest concrete fixes."
    }
  ]
}

(Names can’t be general, explore, vision, verify, or computer — those are reserved.)

  • Computer use. A built-in computer sub-agent, backed by agent-desktop, drives your macOS desktop. The preferred workflow is accessibility computer_snapshot → stable refs (@e1) → actions like computer_click / computer_type / computer_scroll, with computer_screenshot for visual confirmation. This requires granting Accessibility permission to your terminal app in System Settings, and agent-desktop currently targets macOS only.

  • Shuru microVM sandbox. Enable --sandbox (or /sandbox in the TUI) and shell commands run inside an isolated Shuru microVM — network off by default, opt-in with --allow-net/--allow-host, port forwards via --port 8080:80, plus CPU/memory/disk limits and checkpoints. macOS 14+ on Apple Silicon only. On Intel Macs or Linux you’re running against your host with no sandbox, which is a real security consideration given the community-maintained caveat above.

  • --verify. Point it at an app and it inspects, builds, boots, and runs browser smoke checks in a sandbox, producing a report with screenshots and video. This “prove it works” evidence loop is one of the more differentiated features.

It also supports the now-standard extension surface: MCP servers (/mcps or mcpServers in settings), Agent Skills (.agents/skills/<name>/SKILL.md), hooks on lifecycle events (PreToolUse, PostToolUse, SessionStart, etc.), and AGENTS.md merged from git root down to your cwd (Codex-style), with AGENTS.override.md winning per directory.

What Does It Cost to Run?

grok-cli itself is free and MIT-licensed. Your cost is Grok API usage. Per our PRICING-FACTS reference, Grok 4.5 runs about $2 per million input tokens and $6 per million output tokens — a typical 30K-in/5K-out coding task lands around $0.09. That’s competitive with the cheaper Claude and Gemini tiers, and the --batch-api flag knocks it down further for unattended jobs. (Always confirm current pricing on x.ai before budgeting — model prices move.)

Community Reactions

Because grok-cli predates xAI’s official open-source release, the community narrative is mostly “the interesting third-party option.” Recurring themes from GitHub, DeepWiki, and roundup coverage:

  • The Telegram remote control is the headline. Nearly every writeup leads with “drive your coding agent from your phone.” It’s a genuinely novel workflow that neither Claude Code nor the official Grok Build ships.
  • “Not affiliated with xAI” trips people up. A common point of confusion is assuming this is the official Grok CLI. It isn’t — and now that xAI has open-sourced Grok Build, expect some users to migrate to the official harness for anything production-critical.
  • Fast-moving changelog. Recent releases show active maintenance — a ripgrep-WASM grep tool (#263), the STT swap (#265/#266), and ongoing sandbox work — but flags can shift between versions.
  • Terminal friction. The most common install complaint is OpenTUI not rendering, fixed by switching to WezTerm/Ghostty/Kitty.

Honest Limitations

grok-cli is genuinely capable, but be clear-eyed:

  1. It’s community-built, not xAI-official. You’re trusting a third-party maintainer with an agent that edits files and runs shell commands. Now that Grok Build exists as the official option, that trade-off is harder to justify for sensitive codebases.
  2. Grok API only. No provider abstraction — you need an xAI API key and you’re locked to Grok models. If you want to swap in Claude or GPT, this isn’t your tool.
  3. macOS-centric power features. Computer use (agent-desktop) and the Shuru sandbox are macOS-only, and the sandbox specifically needs Apple Silicon on macOS 14+. Linux and Intel-Mac users lose the two features that most reduce risk.
  4. Remote control has a footgun. The Telegram bridge is powerful, but a leaked/approved bot token means someone can remotely drive an agent with shell access. The README’s “treat the bot token like a password” is not boilerplate.
  5. The grok command name collides. Installing this puts a grok binary on your PATH that is not xAI’s official grok. If you also install Grok Build, you’ll need to sort out which grok wins — a real source of confusion.
  6. Trademark caveat. “Grok” is xAI’s trademark; this project uses it under a community disclaimer. That’s fine legally, but it’s a reminder of the unofficial status.

grok-cli vs. Grok Build vs. the Field

grok-cli (grok-dev)Grok Build (official)Claude Code
MaintainerSuperagent (community)xAI (official)Anthropic
LicenseMITApache 2.0Proprietary
LanguageTypeScriptRust—
ProviderGrok API onlyGrok APIClaude only
Remote control✅ Telegram❌❌
Computer use✅ (macOS)⚠️ via extensions⚠️ via MCP
Sandbox✅ Shuru microVM (Apple Silicon)✅ sandboxed exec✅
External PRs✅ MIT, fork away❌ read-only source❌

The honest summary: Grok Build is the safer production choice now that it’s open. grok-cli is the more experimental option with unique remote-control and computer-use tricks. And if you’re not committed to the Grok ecosystem, a provider-agnostic tool or Claude Code may fit better.

FAQ

Is grok-cli the official xAI Grok CLI? No. grok-cli (npm grok-dev) is community-built by Superagent and explicitly not affiliated with xAI. xAI’s official open-source agent is Grok Build, a separate ~840K-line Rust project. They both use the grok command name, which causes real confusion.

Do I need a Grok API key? Yes. grok-cli only talks to xAI’s Grok API, so you need a key from x.ai. There’s no way to point it at Claude, GPT, or a local model — it’s Grok-only by design.

How does the Telegram remote control work? You create a bot with @BotFather, set the token, and run /pair from Telegram to approve your account once. After that you can DM the bot to drive the agent from your phone — including voice notes, which get transcribed via Grok’s STT endpoint. The CLI process must stay running because long polling lives inside it.

Does grok-cli work on Linux or Windows? The core agent and headless mode run cross-platform in a modern terminal, but the two power features — computer use (agent-desktop) and the Shuru microVM sandbox — are macOS-only, and the sandbox additionally requires Apple Silicon on macOS 14+. Linux users get the agent but not the desktop automation or sandbox.

Is it safe to run? It’s an agent with file-edit and shell access, maintained by a community team rather than xAI, so apply the usual caution: prefer the sandbox where available, don’t approve untrusted Telegram users, protect your bot token, and consider Grok Build for anything sensitive. The MIT license means you can audit and fork the TypeScript source yourself.

How much does it cost? The tool is free and MIT-licensed; you pay for Grok API usage. Grok 4.5 is roughly $2/$6 per million input/output tokens (~$0.09 for a typical coding task), and the --batch-api flag lowers cost for unattended runs. Check x.ai for current pricing.

Verdict

grok-cli is a genuinely interesting community coding agent — the Telegram remote control and computer-use sub-agent are features you won’t find in most competitors, and the headless --format json / --batch-api story makes it a real candidate for automation. But its moment is complicated by timing: xAI open-sourced the official Grok Build just weeks ago, which reframes grok-cli from “the open Grok agent” to “the unofficial, more experimental Grok agent.”

Use grok-cli if you want the phone-driven remote control, the microVM sandbox, and a hackable TypeScript codebase you can fork. Use Grok Build if you want the official, production-grade harness. Either way, if you’re building on the Grok API in 2026, it’s a good problem to have two solid open-source agents to choose from.

Sources