Install Grok Build and survive first run

It is 6:50 p.m. Slack lights up: “install grok and fix the warehouse export before 7.” Finder still shows yesterday’s production clone on the Desktop, folder name warehouse-sync-prod-0817, 2.1 GB, last modified 11:48 p.m. The .env in that tree still has Tuesday’s staging password in plain text. You are one cd away from pointing a brand-new coding agent at live credentials.

This is Part 16 of the Grok series. Everyday chat lives in a browser tab. Grok Build is different. It is a terminal coding agent that can read and change a real project folder. If the four Grok doors still blur (chat, Build, Imagine, API), keep Grok chat, Build, Imagine, and the API open. Here we install the CLI, log in, and survive first run without touching production.

Product names, plan labels, and who can sign in still move. Treat the notes below as a field guide as of writing (August 2026). Re-check x.ai/build and the Grok Build overview the week you roll this out for a team. The May 25, 2026 launch post said SuperGrok and X Premium Plus subscribers could install the early beta. Confirm that on the live page before you promise seats in a standup.

What the grok install puts on the machine

What the grok install puts on the machine, and what it does not
Official Mac/Linux and Windows install commands, then how to start in a sandbox folder
Browser login vs XAI_API_KEY when there is no browser
Why grok inspect is the first command after “it opened”
Plan mode in plain English, plus a first-run ritual: one read-only question, one tiny reviewed change

What Build puts on the machine

Grok Build is a coding agent you run from a terminal. The interactive screen is a TUI (text user interface): full screen, mouse support, a prompt at the bottom. You can also run it headless with grok -p for a single prompt, or through ACP (Agent Client Protocol) inside other apps. The same family of model that powers the agent, Grok 4.6 as of writing, also exists on the xAI API. That API path is a different bill. Do not assume a chat subscription and API credits share a wallet.

The install gives you a grok command. It does not give you a second copy of grok.com. It does not mount your whole hard drive as a playground unless you start the command in a wide folder. Working directory is the blast radius. If you type grok in ~/Desktop, the agent can see every clone you left there, including the 2.1 GB production tree from last night.

Once it is running, Build can read files, propose edits, run shell commands you approve, and pick up repo conventions. Official docs say it reads AGENTS.md, skills, plugins, hooks, and MCP servers in the project. You do not need any of that on night one. You need a sandbox folder, a login, and a habit of watching the first diffs.

Rule of thumb: Chat answers with words. Build works in a folder. Open Build only in a directory you would let a new contractor browse.

Grok Build surfaces: TUI in a project folder, headless grok -p, and ACP in other apps. Chat apps stay in the browser.

Public branding on xAI pages still moves (some marketing currently says SpaceXAI). In this series we say xAI and Grok. If a screenshot in a vendor blog uses a different parent name next month, the CLI command is still grok.

Install Mac/Linux and Windows

Use the official bootstrap. Do not grab a random GitHub zip a coworker forwarded in Slack. On macOS or Linux:

curl -fsSL https://x.ai/cli/install.sh | bash

On Windows PowerShell:

irm https://x.ai/cli/install.ps1 | iex

Those two lines are the vendor install as of writing. They pull a script and run it. That is normal for this product and still worth a pause on a locked-down work laptop. If security has a software allow-list, send them x.ai/build and wait. A shadow install on a personal user account, pointed at a corporate repo, is how the next ticket starts.

After the script finishes, open a new terminal tab so your PATH picks up the binary. Then check that the command exists:

which grok
grok --help

If which grok prints nothing, the shell is still using the old PATH. Quit Terminal.app or Windows Terminal fully, reopen it, and try again. If help text appears, you have a client. You do not yet have a safe session.

Config lives in ~/.grok/config.toml on Mac and Linux. On Windows it is %USERPROFILE%\.grok\config.toml. You do not need to hand-write that file tonight. Know the path so you can find models, MCP servers, and plugins later. Project-level extras can also live in a repo .grok/config.toml. Official docs put most personal model settings in the user file, and keep project files for things like MCP and plugins. Labels move. grok inspect will tell you what this version loaded.

First grok in a sandbox

Do not start in warehouse-sync-prod-0817. Make a toy folder, or clone a throwaway copy without secrets. A Desktop production tree is a trap because the name looks harmless (“sync”) and the .env is already there.

A sandbox that is good enough for first run:

A folder you created today, with a tiny README and one Python or JS file
Or a fresh git clone of an open sample, with no production .env
Git initialized, so you can see a diff and roll back
No customer exports, no payroll CSVs, no VPN secrets sitting in the tree

Example:

mkdir -p ~/sandbox/warehouse-export-toy
cd ~/sandbox/warehouse-export-toy
git init
printf '%s\n' '# toy export' > README.md
git add README.md
git commit -m "start toy sandbox"
grok

That last line opens the TUI in this folder. If you already have a small internal sample repo, clone that instead and skip the printf lines. The point is the cd. The agent inherits your current directory. Starting in ~ or ~/Desktop is how yesterday’s 2.1 GB clone enters context.

First-run path: sandbox folder, grok command, login, inspect, read-only question, then one tiny reviewed edit.

Official first prompts from the docs are boring on purpose: “Explain this repo.” and “Walk me through this file,” with an @ path. Boring is correct. A first prompt that says “fix production and push” is how you skip the only night you will still be careful.

Auth: browser vs API key

On first launch, Grok opens a browser so you can sign in. That is the path for a normal laptop with SuperGrok or X Premium Plus access (as marketed at the May 2026 launch; re-check). Finish the browser flow. Come back to the TUI. If the browser tab sits on an error, do not keep retrying inside a production clone. Fix auth in the sandbox.

Headless machines, SSH sessions, and some CI images have no browser. Official docs say to export an API key, then start grok:

export XAI_API_KEY="xai-..."
grok

Mint that key in console.x.ai. Chat subscription money and API credits are separate systems. A SuperGrok login in the browser does not automatically fund XAI_API_KEY usage. If you paste a real key into a screenshot, a gist, or a Slack thread, rotate it. The placeholder in this post is xai-... on purpose.

For a one-shot question without the TUI:

grok -p "Explain this codebase"

Headless is useful later for scripts. It is a poor first-run teacher because you lose the approve/deny prompts you still need to see. Stay in the TUI tonight. Save grok -p for a prompt you would let run without a human hovering, which on night one is almost nothing.

If login works and the TUI is up, run inspect from a second terminal in the same folder, or use the inspect command the client exposes:

cd ~/sandbox/warehouse-export-toy
grok inspect

Inspect lists what Grok discovered: config sources, instruction files, skills, plugins, hooks, MCP servers. On a fresh toy repo the list should look thin. That is success. A first inspect that already shows nine MCP servers and a browser plugin means you started in someone else’s fully loaded tree. Back out. You wanted a sandbox, not a Christmas tree.

What a clean first inspect can look like (toy, labels will vary):

Inspect item	Clean sandbox	Why you care
User config	`~/.grok/config.toml`	Personal models and defaults
Project config	none yet	No surprise MCP on night one
Rules / AGENTS.md	none yet	You have not written house rules
Skills / plugins / MCP	0 / 0 / 0	Nothing extra is waiting to hang the session

Plan mode in one paragraph

Plan mode is planning first. The agent writes a plan you can approve, comment on, or rewrite before it edits the rest of the tree. In the TUI, enter it with /plan (optional description) or cycle modes with Shift+Tab. Reopen the plan with /view-plan. Official docs say the file-edit gate is independent of permission mode: even if you later turn on a more automatic approve setting, plan mode still holds ordinary file edits until you accept the plan. Use it the moment the task is bigger than “rename one function.” Skip it for “what does README.md say.”

First-run ritual

Permission language in the product is still moving. As of writing you will meet some mix of ask (watch and approve tools), auto (a classifier lets boring tools through), and always-approve (skips prompts; deny rules and hooks still apply). Default to watch/approve. Do not start first run in always-approve. Do not pass a “clean unused files” prompt to headless grok -p on a laptop that still holds production.

Permission vibe	When to use
Ask / watch (default)	First week, any folder you care about, any prompt that might edit
Auto (classifier)	After you trust this repo and the task is small and local
Always-approve	Almost never on first run; never against prod or a secrets directory
Headless `grok -p`	After you have a prompt you would let run without hovering; not tonight

Do the ritual in order. If you skip a step, start over. The warehouse export can wait 20 minutes. A bad first session will cost you the evening.

Confirm you are in the sandbox with pwd. If you see warehouse-sync-prod-0817, cd out.
Run git status. A dirty tree with leftover secrets is not a first-run folder.
Start grok. Finish browser auth, or set XAI_API_KEY only if you have no browser and you understand that is API money.
Run grok inspect. If the list is crowded, you are in the wrong tree.
Ask one read-only question: “Explain this repo in one screen. Do not edit files.”
Ask one tiny change: “Add a single sentence to README.md that says this folder is a toy sandbox. Do not touch other files.”
Read the diff. If the agent also “helpfully” rewrote punctuation in three other files, reject those hunks.
Keep or discard with git. Rollback is git, not a magic undo button inside the TUI.

A read-only first question trains you to see how the agent looks at the tree. A one-sentence README edit trains you to read a diff while the stakes are still a toy folder. If both go well, stop. Close the TUI with /quit. First run is over. The 6:50 p.m. Slack can get a honest reply: “CLI is installed. I will touch the real export tomorrow in a branch, with plan mode on.”

If you want a slightly richer toy than a README, add a five-line Python file and ask the agent to add a docstring. Same rule: one file, one change, you read the diff. Do not paste the Tuesday staging password into the prompt “for context.”

Install with curl -fsSL https://x.ai/cli/install.sh | bash (Windows

Mistake	What happens	Do this instead
Install, then `cd` into last night’s prod clone	Agent can see `.env`, exports, and 2.1 GB of history	Sandbox folder first, then `grok`
Treat SuperGrok login as API credit	Headless runs fail or bill a second wallet	Browser auth for the TUI; Console key only when you mean API
First prompt is “fix everything”	Wide diffs you will not finish reviewing by 7 p.m.	Read-only question, then one file
Always-approve on night one	Shell commands run while you are still reading the docs	Watch and approve
Skip `grok inspect`	You inherit someone else’s MCP and plugins	Inspect, then decide

Install with curl -fsSL https://x.ai/cli/install.sh | bash (Windows: (run)

Tonight: install with the official script, open a sandbox, log in, inspect, ask one read-only question, land one tiny README sentence, and stop. Tomorrow, pick a second toy file and practice the loop this series uses next: explore, change, check. That is Grok Build project loop: explore, change, check, the next part in the Grok series. If you still mix chat tabs with the folder agent, reread the four surfaces before you point Build at work code.

If your company has not approved the CLI, do not sneak it onto a laptop that holds customer data. Send the official install page, name the sandbox rule, and wait. The export ticket will survive one more morning. The leaked staging password might not.

Install with curl -fsSL https://x.ai/cli/install.sh | bash (Windows: 3

Install with curl -fsSL https://x.ai/cli/install.sh | bash (Windows: irm https://x.ai/cli/install.ps1 | iex)
The command is grok. Config lives in ~/.grok/config.toml
Start only in a sandbox. Yesterday’s Desktop clone is not a sandbox
Browser login for the TUI; XAI_API_KEY only when there is no browser and you mean API spend
Run grok inspect, ask a read-only question, then one tiny reviewed edit
Plan mode (/plan or Shift+Tab) before any task that might touch more than one file
May 2026 launch eligibility was SuperGrok and X Premium Plus. Re-check before you brief the team

Sources

Research and further reading used for this article:

xAI: Grok Build (install command and product home)
xAI docs: Grok Build overview (TUI, grok -p, config.toml, grok inspect, first prompts)
xAI: Introducing Grok Build (May 25, 2026 launch, SuperGrok and X Premium Plus note, plan mode, /feedback)
xAI docs: Grok 4.6 (model that powers Build as of writing)
xAI Console (API keys when you need XAI_API_KEY)
xAI: Grok FAQ (plan and product questions to re-check)
Analytics Made Simple: Learn (other paths on this site)

Keep going

Same lessons in your feed

Short diagrams and hooks on Instagram, X, and Facebook.

@analyticsmadesimple Follow @AnalyticsSimply Follow Analytics Made Simple Follow