Grok explained
Grok CLI explained: xAI's Grok Build and the unofficial grok-cli
Updated November 17, 20268 min read
Search for Grok CLI and you will find two different programs that both start with the grok command. One is Grok Build, xAI's own coding agent for the terminal. The other is grok-cli, a free, open-source project by independent developers that talks to the Grok API. This page shows which is which, how to install each one, and how Grok holds up as a coding agent.
Two different tools called Grok CLI
Grok Build (official, by xAI)
xAI's coding agent. Runs as a full-screen terminal app, headless in scripts, or inside other apps. Sign in through your browser with your xAI account, or use an XAI_API_KEY.
grok-cli (community, on GitHub)
An MIT-licensed project from superagent-ai. It describes itself as an open-source coding agent for the Grok API. You bring your own GROK_API_KEY. Not made or endorsed by xAI.
It is easy to mix them up. Both are terminal coding agents, both use Grok models, and both put a command called grok on your computer. Tutorials rarely say which one they mean. A quick test: if a guide installs from x.ai, it is Grok Build. If it installs from GitHub or with bun add -g grok-dev, it is the community grok-cli.
The community project says plainly in its README that it is "not affiliated with, endorsed by, or sponsored by xAI Corp." That doesn't make it bad. It just means xAI doesn't support it, and its features follow its own developers' plans.
Grok Build vs grok-cli side by side
| Grok Build (xAI) | grok-cli (community) | |
|---|---|---|
| Who makes it | xAI | superagent-ai and contributors |
| Command | grok | grok |
| Install | One-line script from x.ai, for Mac, Linux and Windows PowerShell | Bash install script from GitHub, or bun add -g grok-dev |
| Needs | Nothing extra | Bun (bundled by the install script) |
| Sign-in | Browser sign-in, or XAI_API_KEY | GROK_API_KEY only |
| Settings file | ~/.grok/config.toml | ~/.grok/user-settings.json and .grok/settings.json |
| Run from scripts | grok -p "..." | grok -p "...", plus --format json |
| Project rules | Reads AGENTS.md, CLAUDE.md and Cursor rules | Supports Agent Skills and hooks |
| Extras | Plan and auto modes, worktrees, dashboard, plugins | Telegram remote control, X search, a macOS desktop helper |
| Licence | Official xAI product | MIT, open source |
| Docs | docs.x.ai/build | GitHub README |
Both settings files sit in a folder called .grok in your home folder. If you ever install both tools, keep that in mind before you start deleting files to fix a problem.
Setting up Grok Build, the official xAI Grok CLI
These commands come from xAI's Grok Build docs.
macOS and Linux
curl -fsSL https://x.ai/cli/install.sh | bashWindows (PowerShell)
irm https://x.ai/cli/install.ps1 | iex- Open a new terminal after the install finishes, so it can find the
grokcommand. - Move into your project folder with
cd. - Type
grok. The first time, a browser window opens so you can sign in to your xAI account. - On a server or CI machine with no browser, set
XAI_API_KEYfirst and then rungrok. - Try a first request:
Explain this repo.or@src/main.rs walk me through this file.
The three Grok Build modes
Press Shift+Tab to move between modes (modes docs):
- Plan: Grok writes a plan and may only edit that plan file until you approve it. Start it with
/plan. - Auto: a checker approves safe actions by itself, and risky ones still come to you. Switch it with
/auto. - Always-approve: no permission questions, though your deny rules and hooks still apply. Use
/always-approveor start withgrok --always-approve, and only on work you have backed up.
An optional sandbox (Landlock on Linux, Seatbelt on macOS) limits what approved commands can reach. It is off by default.
Grok Build commands
| Command | What it does |
|---|---|
grok -p "Explain this codebase" | Runs one prompt with no screen and prints the answer |
grok -p "..." --output-format streaming-json | Same, with structured output for scripts |
grok inspect | Lists the config, rules, skills, hooks and MCP servers it found |
grok sessions list | Shows past sessions you can go back to |
grok worktree list | Shows Git worktrees created for sessions |
/model and /effort | Change model and thinking effort |
/resume, /fork, /rewind | Go back to an old session or an earlier turn |
/btw <question> | Ask a side question without stopping the main task |
/import-claude | Copy over your Claude Code settings |
/usage | See how many credits you have used |
Grok Build reads AGENTS.md in your project, and also CLAUDE.md, .claude/rules/ and .cursor/rules/, so a project set up for Claude Code or Cursor works straight away. Settings and custom models go in ~/.grok/config.toml (on Windows, %USERPROFILE%\.grok\config.toml). If the colours or copy and paste look wrong, run /terminal-setup and it suggests fixes for your terminal.
Setting up the community grok-cli from GitHub
The community grok-cli uses its own key from the xAI API console rather than a browser sign-in. From its README:
# Install script (bundles the Bun runtime)
curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash
# Or, if you already use Bun
bun add -g grok-dev
# Give it your key, then start it
export GROK_API_KEY="your-key"
grok- Bun is a JavaScript runtime (the engine that runs the program). The package install needs it; the install script brings its own copy.
- Settings: your key, hooks and sub-agent options live in
~/.grok/user-settings.json. The model for one project lives in.grok/settings.json. - Other variables:
GROK_BASE_URL(defaulthttps://api.x.ai/v1),GROK_MODELandGROK_MAX_TOKENS. - Headless runs:
-pruns one prompt and exits,-dpicks the project folder,--format jsonstreams events, and-s latestresumes the last session. - Cheaper unattended jobs:
--batch-apisends work through xAI's Batch API. - Model list: run
grok modelsto see what your key can use.
Extra features include sub-agents (on by default), image and video generation tools, MCP servers, scheduled headless runs, and control from Telegram. Its optional sandbox needs macOS 14 or later on Apple silicon. The README gives a bash install script but no PowerShell one, so on Windows you would need a bash shell such as WSL or the Bun route.
Watch out
Because this tool is unofficial, xAI support can't help you with it. Read the code or the issue tracker before giving it a key tied to a card with no spending cap.
Which grok command is on my computer?
If you followed two different tutorials, you may have both tools and not know which one starts when you type grok. Here is how to check:
- Ask the system where
groklives:which grokon Mac or Linux,where.exe grokin Windows PowerShell. - Run
grok inspect. Grok Build prints the config and rules it found. The community tool's README does not list this command, so an error here points to the community tool. - Look in your home folder's
.grokfolder:config.tomlpoints to Grok Build,user-settings.jsonto the community tool. - Pick one and remove the other. The community tool's README gives
grok uninstallfor a script install. If you installed it with Bun,bun remove -g grok-devremoves it.
Using both is possible, but you would have to call one by its full path every time. For most people one is enough. On Windows, where.exe lists every match in the order Windows searches, and the first line is the one that runs when you type grok. After removing a tool, close the terminal and open a fresh one so it forgets the old location. If grok then says it can't be found, run the install line for the tool you kept again.
How Grok compares as a coding agent
We won't claim Grok is better or worse than Claude Code or Codex at writing code. There are no fair, independent test results we could point you to that match how you work, and coding agents change month to month. What we can compare is what each tool lets you do.
On features, Grok Build is in the same family as Claude Code and Codex. According to xAI's docs it has plan mode, subagents for parts of a bigger job, background tasks (including /loop to repeat a prompt on a timer), Git worktrees, sessions you can resume, fork, rewind and share, an agent dashboard (/dashboard), plus skills, plugins, hooks and MCP servers. It can also run headless or inside other apps through the Agent Client Protocol (grok agent stdio). One unusual extra is image and video generation from the terminal with /imagine and /imagine-video. xAI's docs name Grok 4.7 as its latest model on the API, as of November 2026.
Trying it costs little effort. Because Grok Build reads CLAUDE.md and AGENTS.md and /import-claude copies your Claude Code settings, you can point it at a project you already run with another agent and give both the same task. That one test on your own code tells you more than any ranking. Our best AI coding agents roundup and Codex vs Claude Code comparison cover the other options, and the Codex CLI reference shows the closest rival command by command.
If you do end up using Grok next to other agents, VibeCodingDeck supports Grok out of the box. You can run a swarm (a lead agent plus a small team) where Grok takes one role and Claude or Codex takes another, each on its own copy of the project, then merge the best work back. VibeCodingDeck runs on Windows 10/11 and Apple silicon Macs and uses your own accounts; it costs $29/month or $249/year as of November 2026.
Grok Build pricing and access
Grok Build runs on your xAI account. As of November 2026, xAI sells subscriptions through The X Subscription, which bundles Grok, Cursor and X, and older SuperGrok and X Premium plans continue. The Grok Build pages don't say which plans include it or how much use each one gets, so check x.ai/pricing before paying. If you use an API key instead, you pay xAI's API rates for what you use. Type /usage inside Grok to see your credits.
The community grok-cli has no plan of its own. It is free software, and every request is billed to the xAI API key you give it.
Grok CLI: short answers
Is there an official Grok CLI from xAI?
+
Yes. It's called Grok Build and you start it with grok. The grok-cli project on GitHub is a separate community tool that xAI doesn't make or endorse.
How do I install Grok Build?
+
Run curl -fsSL https://x.ai/cli/install.sh | bash on Mac or Linux, or irm https://x.ai/cli/install.ps1 | iex in Windows PowerShell. Then open a new terminal and type grok.
Which API key does each Grok CLI use?
+
Grok Build uses a browser sign-in, or XAI_API_KEY where there's no browser. The community grok-cli uses GROK_API_KEY.
Is Grok good for coding?
+
Grok Build has the main features of Claude Code and Codex, such as plan mode, subagents and worktrees. How well it codes on your project is best judged by giving it and another agent the same task.
Sources
Run up to 12 AI coding agents in one window.
Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.
Get startedKeep reading
Buyer's guide
The best AI coding agents in 2026, sorted by how you work
Command reference
Codex CLI command reference: from install to codex exec
Head to head
Codex vs Claude Code: seven rounds and an honest verdict
Explainer
AI agent orchestration for coding: the words, the patterns and a worked example
Explainer
Agentic coding, explained in plain English