Reviewed by Jonathan West · Updated Aug 17, 2026

How to Use Grok Build: A Step-by-Step Setup Guide

From install to your first reviewed task, using xAI's terminal coding agent.

Reviewed by Jonathan West · Updated Aug 17, 2026

This tutorial walks through how to use Grok Build from a clean install. You will install the CLI, authenticate, run a task in Plan Mode, and review the result.

Grok Build requires an active SuperGrok or X Premium+ subscription. If you have not compared it against other terminal agents yet, read our Grok Build explained guide first.

The steps below cover the interactive terminal workflow and the headless mode you would use in scripts or CI.

How to Install Grok Build

Install Grok Build with a single command on macOS or Linux: curl -fsSL https://x.ai/cli/install.sh | bash. Windows users run the equivalent PowerShell script from x.ai/cli/install.ps1.

The installer needs a qualifying SuperGrok or X Premium+ subscription to unlock the CLI on first use, so sign in with that account during setup.

Once installed, type grok build in any project directory to start a session.

  • macOS/Linux: curl -fsSL https://x.ai/cli/install.sh | bash
  • Windows: PowerShell installer at x.ai/cli/install.ps1
  • Requires an active SuperGrok or X Premium+ subscription.
  • Run grok build in a project directory to launch a session.

Want a guided Grok Build rollout with the right authentication policy and review workflow for your team? We handle setup and your first automated tasks.

Book a Consultation

Authenticating Grok Build

Grok Build authenticates through your browser on first launch, the same account that holds your SuperGrok or X Premium+ subscription.

In non-browser environments, such as a headless server or a CI runner, set the XAI_API_KEY environment variable instead of signing in interactively.

Run grok inspect at any point to see which configuration and models the CLI has discovered for your current setup.

  • Browser-based sign-in on first launch.
  • XAI_API_KEY environment variable for non-browser or CI environments.
  • grok inspect shows the active configuration and models.

Your First Run: Plan Mode

Give Grok Build a task in plain language, and it starts in Plan Mode by default for anything beyond a trivial edit. It lays out the files it intends to touch and the steps it will take before changing anything.

Review the plan the same way you would review a pull request description. Approve it to let the agent proceed, or redirect it if the proposed approach misses your intent.

For a large task, Grok Build can split the work across up to eight parallel subagents, each working in its own Git worktree, so you review one coherent plan even though multiple agents execute it.

  • Describe the task in plain language.
  • Review the proposed plan before any file changes happen.
  • Approve to proceed, or redirect if the plan is off-target.
  • Larger tasks can split across parallel subagents automatically.
Treat the plan step like a PR description review: read it fully before you approve, especially on your first few sessions.

Targeting Specific Files and Output Formats

Reference a specific file directly in your prompt with the @ syntax, for example @src/main.rs, to focus the agent's analysis on that file instead of the whole repository.

Grok Build also supports a streaming-JSON output format, useful when you are piping its output into another tool or logging system rather than reading it in the terminal.

Use the /feedback command inside a session to report a bug or request a feature directly to xAI.

  • @path/to/file.ext focuses analysis on one file.
  • Streaming-JSON output for piping into other tools.
  • /feedback reports bugs or requests directly from the session.

Running Grok Build Headlessly

Run Grok Build without the interactive terminal UI using the -p flag, which suits scripts, scheduled jobs, and CI pipelines.

Headless mode follows the same plan-search-build loop as the interactive session, just without a human approving each plan in real time, so scope your automated tasks narrowly and add your own review step downstream.

Grok Build also supports the Agent Client Protocol (ACP), which lets other applications or bots drive it programmatically instead of through the CLI directly.

Across our own scheduled routine-automation runs, we gate a new agent's API-key auth and repo scope before it ever touches a shared codebase unattended, then widen access only after a few clean headless runs. Apply the same staged rollout to Grok Build rather than pointing -p at a production repo on day one.

  • -p flag runs Grok Build headlessly for scripts and CI.
  • Same plan-search-build loop, without interactive approval.
  • ACP support lets other apps or bots drive Grok Build directly.
  • Scope unattended tasks narrowly and review changes downstream.

Frequently Asked Questions

  • Run curl -fsSL https://x.ai/cli/install.sh | bash on macOS or Linux, or the PowerShell installer at x.ai/cli/install.ps1 on Windows. You need an active SuperGrok or X Premium+ subscription to unlock the CLI.
  • Add the -p flag to run Grok Build headlessly, which suits scripts, scheduled jobs, and CI pipelines. It follows the same plan-search-build loop as the interactive session but without a human approving each plan in real time.
  • Only in non-browser environments like a headless server or CI runner. On a normal desktop or laptop, Grok Build authenticates through your browser using the account that holds your SuperGrok or X Premium+ subscription.
  • Reference the file directly in your prompt using the @ syntax, for example @src/main.rs, to focus the agent's analysis on that file instead of scanning the whole repository.
  • Plan Mode is Grok Build's default step for non-trivial tasks: the agent lays out the files it intends to touch and its intended approach, and you approve or redirect the plan before any file changes happen.

Rolling Out Grok Build or Another Coding Agent Across Your Team?

Layer3 Labs handles the install, authentication policy, and first automated workflows for new AI coding agents like Grok Build, so your team starts productive safely.

Book a Free AI Workflow Audit