grok-cli: a community coding agent for the xAI Grok API

What grok-cli solves, and who it is actually for

Most coding agents assume you will pick one vendor's model and stay there. grok-cli assumes the opposite: you already pay for xAI's Grok API and want a terminal agent that uses it well. The README frames the value as real-time X search, web search, the full Grok model lineup, sub-agents on by default, and remote control over Telegram.

The audience is narrow and specific. You need a Grok API key from x.ai, a modern terminal emulator, and a willingness to run a community project. The README carries an explicit disclaimer that the project is community-built, open source, and not affiliated with, endorsed by, or sponsored by xAI Corp, and that Grok is a trademark of xAI. If your procurement process requires a vendor-supported binary, this is the wrong shape of tool regardless of how well it works.

Where it earns its place is the combination of headless mode and scheduling. A one-shot `grok --prompt` call fits CI, and recurring schedules backed by a daemon fit overnight or weekly jobs. That is a different centre of gravity from an agent you sit in front of all day.

How the agent is put together: Bun, OpenTUI and sub-agents

The stack is TypeScript on Bun, with the interactive interface built on OpenTUI (`@opentui/core` and `@opentui/react`). The package publishes a single binary entry, `grok`, pointing at `dist/index.js`, and declares `"type": "module"`.

Model access goes through the Vercel AI SDK, specifically `ai` and `@ai-sdk/xai`, with `@ai-sdk/provider-utils` alongside. Tool integrations come from `@modelcontextprotocol/sdk` and `@ai-sdk/mcp`, so MCP servers are part of the design rather than an afterthought. The Telegram remote control is built on `grammy`, and code search leans on a bundled `ripgrep` package. There is also `@coinbase/agentkit` in the dependency list, though the README excerpt does not describe what it drives.

The sub-agent model is the part worth understanding. Sub-agents are on by default, and one of them is a built-in `computer` sub-agent backed by `agent-desktop`. Its documented workflow is snapshot, then refs, then action, then snapshot again, using accessibility snapshots with stable references like `@e1` rather than pixel coordinates. Tools named `computer_snapshot`, `computer_click`, `computer_type`, `computer_scroll` and `computer_screenshot` are listed, with the README stating that the screenshot tool exists for visual confirmation but that the snapshot-plus-refs path is preferred.

Installing grok-cli and running a first headless prompt

The README gives a one-line installer that pipes a shell script into bash. It fetches the script from the `main` branch of the repository rather than from a package registry, which means you are trusting the branch state at the moment you run it.

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

If you would rather install through a package manager, the alternative requires Bun to be on your PATH. This pulls the published npm package `grok-dev`, which is the package name even though the command is `grok`.

bun add -g grok-dev

Before the agent can do anything, it needs credentials. The repository ships a `.env.example` listing the keys it reads. Copy it and fill in the API key; `GROK_BASE_URL`, `GROK_MODEL` and `GROK_MAX_TOKENS` are all commented out, which tells you the defaults are `https://api.x.ai/v1`, `grok-4.3` and 16384 tokens respectively.

GROK_API_KEY=your_grok_api_key_here
# GROK_BASE_URL=https://api.x.ai/v1
# GROK_MODEL=grok-4.3
# GROK_MAX_TOKENS=16384

With the key in place, the interactive agent is just the bare command with an optional directory. The README shows `-d` for picking a project directory.

grok
grok -d /path/to/your/repo

For a first real use that does not depend on terminal rendering, run headless. The README's example asks the agent to run the test suite and summarise failures, and `--format json` switches the output to a newline-delimited event stream with records such as `step_start`, `text`, `tool_use`, `step_finish` and `error`. That event stream is what you would parse in CI.

grok --prompt "run the test suite and summarize failures"
grok --prompt "summarize the repo state" --format json

Two more flags are worth knowing before you build anything on top. `--max-tool-rounds 30` caps how many tool calls a single prompt may make, and `--batch-api` routes the run through xAI's Batch API for lower-cost unattended work where a delayed result is acceptable. Sessions persist: `grok --session latest` resumes the most recent one, and `grok -s <session-id>` targets a specific session, in interactive mode as well as headless.

Schedules, the daemon, and where the design bites

Scheduling is configured in natural language rather than a config file. The README's example asks for a schedule named `daily-changelog-update` that runs every weekday at 9am and updates `CHANGELOG.md` from the latest merged commits. In the TUI, `/schedule` browses saved schedules.

The constraint is the daemon. Recurring schedules only keep running while the daemon is active, started with `grok daemon --background`. One-time schedules start immediately in the background. If the daemon is not running, a recurring schedule is not a cron replacement, it is a saved definition. Anyone expecting the operating system's scheduler to pick up the slack will be surprised.

Self-management has a similar boundary. `grok update`, `grok uninstall`, `grok uninstall --dry-run` and `grok uninstall --keep-config` are documented, but the README qualifies them as script-installed only. If you installed through `bun add -g grok-dev`, those commands are not the supported path, and you upgrade through Bun instead.

The computer sub-agent is the sharpest limitation. `agent-desktop` currently targets macOS, and host desktop automation needs Accessibility permission granted to the terminal application running `grok`, set under System Settings, Privacy & Security. Screenshots land in `.grok/computer/` by default. The README also notes a failure mode: if Bun blocks the native binary download during install, the documented recovery is to run the package's postinstall script directly.

node ./node_modules/agent-desktop/scripts/postinstall.js

Interactive use has its own soft requirement. The README recommends WezTerm, Alacritty, Ghostty and Kitty for the OpenTUI experience and says other modern terminals may work, which is an admission that rendering behaviour is not guaranteed everywhere. Headless `--prompt` mode does not depend on terminal UI support, so scripting is the safer surface.

grok-cli compared with Claude Code

The comparison people search for is grok-cli against Claude Code, and the difference is not mainly capability, it is the model endpoint and the surrounding plumbing. Claude Code is built by Anthropic around Anthropic's models. grok-cli is built by a community project around xAI's API, and the README states that it uses the publicly available Grok API. If your organisation already has Grok API credits, grok-cli spends them; Claude Code does not.

The second difference is the tool surface. grok-cli exposes `search_x` and `search_web` as agent tools, so live posts and documentation are reachable inside a session. It also exposes image and video generation as agent tools: the README shows prompts that generate a logo, edit a PNG into a watercolour poster, or animate a JPG into a six second clip, with media saved under `.grok/generated-media/` unless you specify a path. Those are Grok platform capabilities surfacing through the CLI, not features you would port to another agent.

The third difference is remote control. Pairing a Telegram bot, configured through `TELEGRAM_BOT_TOKEN` in `.env`, lets you drive a running CLI session from a phone. That is an unusual design choice and a real one, but it also means a bot token is part of your configuration surface.

Model IDs, pricing hints and the licence position

The README lists models including `grok-4.3`, `grok-4.20-non-reasoning` and `grok-4.20-multi-agent-0309`, and says to run `grok models` for the full menu. That same command is described as listing pricing hints. Nothing in the repository states what those hints contain, so treat the command as the source of truth rather than any number quoted elsewhere.

On cost, the honest answer is that grok-cli is free software and the API is not free. The MIT licence covers the code. Your usage bills against your xAI account. `--batch-api` is documented as using xAI's Batch API for lower-cost unattended runs, which is the only cost-reduction mechanism the README describes.

The licence is MIT, and the repository carries a `LICENSE` file at the top level. MIT is permissive: it allows commercial use and modification, and it comes with no warranty. That matters more than usual here because the tool executes commands and, with the computer sub-agent enabled, can act on your host desktop. The licence does not shift that risk to anyone else, and this is not legal advice; if your organisation has a policy on agent tools with host access, read the LICENSE and the disclaimer together before rollout.

What the repository does not tell you

The README does not document rollback for a schedule that has already fired, nor does it describe how to inspect or cancel a one-time schedule that started in the background. It does not state what happens to a running session when the daemon stops. It does not describe concurrency limits for the Batch API path, so the practical ceiling on parallel unattended runs is unknown from the public documentation.

The release history is a second gap. The most recent release listed is `grok-dev@1.1.7` from 2026-05-15, with `1.1.6` on 2026-05-06 and `1.1.5` on 2026-04-17. The last push to the repository was on 2026-07-06, which is inside the six month window, so the project has recent activity. The README does not carry a compatibility or deprecation policy, and it does not say which Bun versions are supported beyond the badge indicating Bun 1.x and TypeScript 5.9.

Finally, the README does not document a Windows install path. The installer is a shell script piped into bash, and the alternative is `bun add -g grok-dev`. If you are searching for grok cli windows, the repository does not answer it.

Editorial conclusion

Adopt grok-cli if you already have a Grok API key and want a terminal agent with X search, web search and scheduled headless runs; the daemon plus recurring schedules is the part most other CLI agents do not offer. Skip it if you are on Windows without a POSIX shell, or if you need a vendor-supported product, because the README states plainly that this is community-built and not affiliated with xAI. Before committing, run grok models to confirm which model IDs your key can reach, and check whether grok update works on your install path, since the README marks self-management as script-installed only.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. superagent-ai/grok-cli on GitHub