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 itxAIsuperagent-ai and contributors
Commandgrokgrok
InstallOne-line script from x.ai, for Mac, Linux and Windows PowerShellBash install script from GitHub, or bun add -g grok-dev
NeedsNothing extraBun (bundled by the install script)
Sign-inBrowser sign-in, or XAI_API_KEYGROK_API_KEY only
Settings file~/.grok/config.toml~/.grok/user-settings.json and .grok/settings.json
Run from scriptsgrok -p "..."grok -p "...", plus --format json
Project rulesReads AGENTS.md, CLAUDE.md and Cursor rulesSupports Agent Skills and hooks
ExtrasPlan and auto modes, worktrees, dashboard, pluginsTelegram remote control, X search, a macOS desktop helper
LicenceOfficial xAI productMIT, open source
Docsdocs.x.ai/buildGitHub 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 | bash

Windows (PowerShell)

irm https://x.ai/cli/install.ps1 | iex
  1. Open a new terminal after the install finishes, so it can find the grok command.
  2. Move into your project folder with cd.
  3. Type grok. The first time, a browser window opens so you can sign in to your xAI account.
  4. On a server or CI machine with no browser, set XAI_API_KEY first and then run grok.
  5. 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-approve or start with grok --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

CommandWhat it does
grok -p "Explain this codebase"Runs one prompt with no screen and prints the answer
grok -p "..." --output-format streaming-jsonSame, with structured output for scripts
grok inspectLists the config, rules, skills, hooks and MCP servers it found
grok sessions listShows past sessions you can go back to
grok worktree listShows Git worktrees created for sessions
/model and /effortChange model and thinking effort
/resume, /fork, /rewindGo back to an old session or an earlier turn
/btw <question>Ask a side question without stopping the main task
/import-claudeCopy over your Claude Code settings
/usageSee 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 (default https://api.x.ai/v1), GROK_MODEL and GROK_MAX_TOKENS.
  • Headless runs: -p runs one prompt and exits, -d picks the project folder, --format json streams events, and -s latest resumes the last session.
  • Cheaper unattended jobs: --batch-api sends work through xAI's Batch API.
  • Model list: run grok models to 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 grok lives: which grok on Mac or Linux, where.exe grok in 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 .grok folder: config.toml points to Grok Build, user-settings.json to the community tool.
  • Pick one and remove the other. The community tool's README gives grok uninstall for a script install. If you installed it with Bun, bun remove -g grok-dev removes 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 started

Keep reading