Why this matters
You already have a repository from your door. New bench: the C0b scratch repo. Already a repo: the tree you proved with git status. This module is sign-in and surviving the TUI in that directory. It is not a second installer chapter.
A screenshot of grok.com does not pass. The artifact is a running TUI, grok --version, and a first session you started on purpose.
If you do not have a repository yet, stop. New bench starts at Folders, not magic. Do not invent an app so this lesson looks official.
Teach
Which directory
| You came from | Launch here |
|---|
| C0b | The scratch repository you just committed. Letters, a price list, a note — that is enough. |
| Already a repo | The same path as your git status paste. Not a second folder. |
grok --cwd path starts in a folder without cd. Use it if you keep launching from the wrong drive.
If grok --version is missing
You should already have the binary from C0a or from the repo door. If you do not:
Windows (PowerShell): irm https://x.ai/cli/install.ps1 | iex — then close the window and open a new PowerShell tab.
macOS / Linux / Git Bash: curl -fsSL https://x.ai/cli/install.sh | bash
No npm i -g. No friend’s .exe. Then:
grok --version
Authenticate
Start Grok:
grok
On first launch, Grok opens a browser so you can sign in at grok.com. After you finish, it stores credentials in ~/.grok/auth.json (on Windows that is %USERPROFILE%\.grok\auth.json). Tokens persist across sessions. Grok refreshes them in the background and asks you to sign in again when they cannot be renewed. Credentials without a server-provided expiry fall back to a 30-day lifetime.
That file is a credential. It is written owner-only on Unix (0600). Anyone who can read it can use your session.
- Prefer full-disk encryption (BitLocker, FileVault, LUKS).
- Do not paste
auth.json into chat, tickets, or a shared drive.
- On a multi-user host, keep your home directory private.
To switch accounts or fix a broken login:
grok login
That replaces the cached session. Default flow is SpaceXAI OAuth at auth.x.ai in the browser. For SSH, Docker, or a box with no local browser:
grok login --device-auth
(--device-code is the same flag.) Grok prints a URL and a code. Open the URL on any device, enter the code, wait for the poll to finish.
Sign out:
grok logout
API key fallback — for CI, or a machine that cannot open a browser. Create a key at console.x.ai, then:
export XAI_API_KEY="xai-..."
grok
$env:XAI_API_KEY="xai-..."
grok
Grok uses the API key only when no session token is active. If you already signed in through the browser, the stored session wins. Run grok logout (or delete auth.json) if you need the key to take effect. There is also enterprise OIDC and an external auth-provider binary; you do not need those for this module.
The TUI you just opened
Two panes:
- Scrollback — the conversation. Your prompts, Grok’s answers, thinking blocks, tool calls, file diffs, and task lists.
- Prompt — the input at the bottom. Type and press Enter.
Tab moves focus between prompt and scrollback. With the scrollback focused, arrow keys select entries; Left/Right collapse or expand them. Enter on a selected block opens a fullscreen viewer.
While a turn is running, Esc cancels it in the default (non-vim) fullscreen TUI and keeps your draft. Ctrl+C on a non-empty draft clears the draft first; a second Ctrl+C on an empty prompt cancels. Idle, two Esc presses within 800ms clear a non-empty prompt, or open rewind if the prompt is empty and there is conversation. Do not mash Esc until you know which of those you wanted.
Type / for slash commands. The ones you need today:
/new — start a fresh session (alias /clear)/resume — pick an old session/session-info — auth method, model, turn count (aliases /status, /info)/doctor — terminal, clipboard, color, input. Run this if the screen looks wrong./quit — leave (alias /exit)
Every conversation is a session, saved under ~/.grok/sessions/. Ctrl+N or /new starts over. grok -c continues the most recent session for the current directory. grok --cwd path starts in a specific folder — use that instead of launching from the wrong drive.
Do not start this session in this LMS, Golf, Explorer, or a client tree you cannot afford to touch. Use the repo from your door.
Worked example
A Windows learner who finished C0b. PowerShell. Windows Terminal.
cd into the C0b scratch repository. git status still works.grok --version already prints a string. They do not run the installer again.grok. Sign in in the browser if this machine has no session.- Send:
What is this directory? List the files you can see. Do not edit anything. Do not run anything that writes.
- Watch the scrollback. Read-only tools do not wait for approval. If Grok asks to write, refuse it.
Tab, expand the tool-call, /session-info, /quit.
Someone who came through Already a repo does the same steps in their proved repository. They do not git init a new practice folder.
If you do not write software. A .txt file is a real file. You are not behind because you do not have src/. If “repository” still means a website, stop and do C0b.
Your turn
Do the exercise c1-l01-e1 in Grok Build. Not on grok.com. Authenticate, launch in the repository from your door, and keep three artifacts: the version string, the path you launched from, and what the first read-only turn actually did.
If Grok offers to “set up the project,” add a .gitignore, or rewrite the README, say no. Today is auth and orientation.
Common failure
grok is not recognized. You skipped the door that installs, or you are in an old terminal / cmd.exe. Open a new Windows Terminal PowerShell tab. If the binary is missing, use the official installer in the box above — once.
Browser never opens. Run grok login. On a remote box, use grok login --device-auth and finish the code on your phone. Do not paste an API key into the TUI prompt as if it were a chat message.
You launched in the wrong tree. Grok’s working directory is wherever you ran the command (or --cwd). If you see client code, /quit, cd to the scratch repo, start again. Sessions are grouped by working directory under ~/.grok/sessions/.
Colors, keyboard, or fullscreen look broken. Run /doctor inside the TUI, or grok doctor from the shell. On Windows, switch to Windows Terminal. Do not spend the hour fighting a 16-color cmd window.
You enabled always-approve because a prompt annoyed you. Turn it off. C2 is permissions. Today you refuse writes.
What’s next
C2 is the rest of the TUI: tools, scrollback, and the permission prompt you will live in. The standing rule starts there — read the diff before you accept an edit.
