Getting Started

Before you begin

You need:

• A computer running macOS, Linux, or Windows.
• An internet connection (for install and sign-in).
• Permission to install software (on work machines, you may need IT approval).
• A way to sign in to Grok (a browser account, or later an API key from the provider console).

You do not need to already know programming, Git, or AI tools. We will introduce each idea when you need it.

What Grok Build is (in plain English)

Grok Build is a program you run in a terminal. You type goals in normal language—like “add a button that saves the form” or “fix the failing test.” Grok can then:

• Read files in your project so it understands the code.
• Edit files (show you the changes, and usually ask permission first).
• Run commands such as tests or installers (again, often with permission).
• Search the web for documentation when needed.

Why not only use a website chatbot? Grok works inside your project folder. It can take multi-step actions—read, edit, run commands—until a goal is done, not just answer questions.

For this site you only need the first mode: type grok, talk to it, get work done. Learn the others in Advanced.

Step 1 — Open a terminal

A terminal is a text window where you type commands.

• macOS: Open Spotlight (Cmd+Space), type Terminal, press Enter. Or find Terminal in Applications → Utilities.
• Windows: Install Git for Windows and open Git Bash (easiest match to Mac/Linux commands), or use PowerShell with the PowerShell installer below.
• Linux: Open your distro’s Terminal app (often Ctrl+Alt+T).

Step 2 — Install Grok

Copy one of the following blocks into your terminal, then press Enter. This downloads the official installer and runs it.

macOS, Linux, or Windows Git Bash

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

What this means, piece by piece:

• curl downloads a file from the internet.
• The URL is the official install script.
• | bash means “run that script.”

Windows PowerShell (if you prefer PowerShell)

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

The PowerShell installer also adds Grok’s folder to your User PATH so the grok command is found later. You may need to close and reopen the terminal after install.

Optional: install a specific version (only if a tutorial asks for one):

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

Later, to update to the newest version anytime:

grok update

Step 3 — Sign in (authenticate)

Authenticate means “prove who you are so Grok can use your account.”

Option A — Browser login (recommended for learning)

1. Type this and press Enter

   grok

2. Watch for a browser window

   Grok should open your web browser so you can sign in with your account (grok.com / SpaceXAI OAuth). Complete the sign-in like any normal website login.

3. Return to the terminal

   When login succeeds, the terminal becomes the full Grok interface (or shows that you are ready). Credentials are saved under your home folder in a file named roughly ~/.grok/auth.json so you are not asked every time.

Useful related commands (you can run these from a normal terminal when Grok is not already open):

grok login              # sign in again or switch accounts
grok login --device-auth  # for remote machines without a browser
grok logout             # sign out and clear saved login

Option B — API key (for servers and automation later)

An API key is a long secret string from a developer console that proves your identity without a browser. Beginners can skip this until they need scripts or CI.

export XAI_API_KEY="xai-paste-your-key-here"
grok

On Windows PowerShell the first line looks different; use the docs for your shell when you get there. Never put real keys into screenshots or public repos.

Step 4 — Check that it works

In a new terminal window (not necessarily inside Grok), run these one at a time:

grok --version

You should see a version number. That proves the program is installed and on your PATH.

grok models

Lists AI models available to you (names of engines Grok can use). You do not need to pick one yet; defaults are fine.

Inside an open Grok session later, you can type /doctor and press Enter. That runs a health check for terminal features (colors, clipboard, and similar options) and suggests fixes. We cover slash commands more in later lessons—for now, know that anything starting with / is a control command for Grok itself.

Three ways to run Grok (only the first matters today)

You will almost always use #1 for learning and building.

Handy launch patterns you will learn over time (do not memorize yet):

# open Grok in the current folder
grok

# continue your most recent chat in this folder
grok -c

# skip most “may I?” prompts (only on trusted machines)
grok --yolo

Guided lab — first proof it works

Follow every step exactly. This creates a tiny practice folder so you cannot hurt a real project.

1. Confirm install

   In the terminal, run grok --version. Write down the version you see.

2. Create a practice folder

   Run these lines one by one (or as a group):

   mkdir -p ~/tmp/grok-lab
   cd ~/tmp/grok-lab
   echo 'console.log("hi")' > hi.js
   pwd

   mkdir creates folders. cd moves you into them. The echo … > hi.js line creates a tiny JavaScript file that prints “hi”. pwd prints where you are—confirm it ends with grok-lab.

3. Start Grok in that folder

   Run grok. Sign in if asked. Wait until you can type at the bottom.

4. Send this exact first message

   Type (or paste) the following, then press Enter:

   Read the file hi.js in this folder. Add a second line that prints the current year using JavaScript. Then show me what changed.

5. If Grok asks permission to edit

   Read the summary. Choose the option that allows the edit (wording varies; look for Allow / Approve / Yes). This is normal and good—you are in control.

6. Confirm on disk

   Leave Grok with /quit if you want a plain terminal, or open a second terminal window. Run:

   cd ~/tmp/grok-lab
   cat hi.js

   You should see two lines: the original “hi” and something involving a year. If yes—you completed Lesson 1.