ki-grok/02-installation-und-erster-start.md

Kapitel 2

Installation und erster Start

Kern in einem Satz: Typisch in unter einer Viertelstunde (Auth- und PATH-Probleme nicht mitgezählt) installierst du grok, meldest dich an und trainierst die drei Muskeln, die den Rest des Buchs tragen: Scope formulieren, Freigaben lesen, Diffs prüfen.

---

2.1 Was du am Ende dieses Kapitels kannst

Du hast ein lauffähiges Binary, eine funktionierende Auth und eine Session in einem bekannten Übungsordner hinter dir. Du weißt, wie du Version und Terminal-Gesundheit prüfst (grok --version, grok doctor / /doctor), und du hast drei sichere Aufgaben durchgespielt, ohne Always-approve und ohne Produktion.

Warum zuerst installieren und üben, bevor Config und MCP kommen: Jede spätere Schicht (Permissions, Headless, Subagents) multipliziert Fehler, die du am Tag 1 noch gar nicht siehst. Ein sauberer First-Start spart Debug-Zeit in Kapitel 10 und 13.

---

2.2 Installation

Offizielle Empfehlung: der Installer von xAI. Danach startest du mit dem Befehl grok.

macOS / Linux / WSL / Git Bash

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

Feste Version pinnen (Platzhalter – nimm die Version, die dein Team pinnen will; aktuell z. B. grok --version / Release-Notes, Buch-Stand 0.2.x):

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

Warum pinnen? Teams und CI brauchen reproduzierbare Agent-Versionen. „Immer latest“ ist bequem lokal und riskant in Pipelines.

Windows PowerShell

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

Feste Version:

$env:GROK_VERSION="0.2.0"; irm https://x.ai/cli/install.ps1 | iex

Der PowerShell-Installer legt typischerweise %USERPROFILE%\.grok\bin in den User-PATH. Alternativen: Git for Windows (Git Bash) oder MSYS2 mit dem Bash-Installer oben. WSL bekommt das Linux-Binary.

PowerShell vs. CMD vs. Git Bash: Die Install-Befehle sind nicht austauschbar. Falsche Shell → kryptische Fehler, obwohl der Rechner „Windows“ heißt.

Zu curl … | bash und irm … | iex

Achtung: Genau dieses Muster ist bei fremden URLs riskant. Hier vertraust du dem offiziellen xAI-Installer einmal. Im Projekt ordnest du fremde curl | bash-Vorschläge des Agenten unter Deny / Ablehnen ein – nicht unter „hilfreich, Allow“.

---

2.3 Verifizieren und aktualisieren

grok --version

Update auf die neueste stabile Version:

grok update

Wie du weißt, dass PATH greift: which grok (Unix) bzw. Get-Command grok (PowerShell) zeigt auf ein Binary unter deinem Home (häufig ~/.grok/bin/grok bzw. %USERPROFILE%\.grok\bin\grok). Fehlt der Befehl: neue Shell öffnen oder PATH prüfen – nicht sofort neu installieren.

Terminal-Gesundheit (Farben, Clipboard, tmux, Sandbox-Hinweise):

grok doctor
# optional maschinenlesbar:
grok doctor --json

In einer laufenden Session: /doctor – und bei angebotenen Auto-Fixes /doctor fix (bzw. gezielte Fixes laut Ausgabe). Warum doctor zuerst bei „TUI sieht komisch aus“? Du trennst „Binary fehlt / PATH falsch“ von „Terminal-Capabilities / Clipboard / tmux“ und von „Login/Key fehlt“.

---

2.4 Anmelden

Browser-Login (Standard)

cd /pfad/zu/einem/bekannten/projekt
grok

Beim ersten Start öffnet Grok den Browser (grok.com / SpaceXAI-OAuth). Nach dem Login liegen Credentials in ~/.grok/auth.json und werden über Sessions hinweg wiederverwendet. Tokens werden im Hintergrund refreshed; wenn das nicht mehr geht, wirst du erneut zum Login aufgefordert.

Erneut anmelden / Account wechseln:

grok login

Flag	Wann
(default / --oauth)	Browser-Login über SpaceXAI OAuth (auth.x.ai)
--device-auth / --device-code	Device-Code-Flow für headless/remote Umgebungen

Abmelden:

grok logout

API-Key (CI, headless, kein Browser)

Key aus der Console (z. B. console.x.ai), dann:

export XAI_API_KEY="xai-..."
grok

Alltag (Default-Grok): Session-Token aus Browser-Login schlägt XAI_API_KEY – deshalb grok logout, wenn du nur den Key willst.
Custom Models (Kapitel 14): davor können per-model api_key / env_key in config.toml greifen (Reihenfolge grob: api_key → env_key → Session → XAI_API_KEY).

Achtung: ~/.grok/auth.json und MCP-Credentials (~/.grok/mcp_credentials.json) sind Dateien mit Secrets (Unix typisch 0600). Nicht in Tickets, Chats oder Shared-Dirs kopieren. Full-Disk-Encryption und privates $HOME / $GROK_HOME auf Multi-User-Hosts sind Pflicht, nicht Nice-to-have.

Enterprise / SSO

Firmen-Login (OIDC/SSO) konfigurierst du erst, wenn Browser- oder Key-Auth nicht greift – Details: User-Guide Authentication und Kapitel 14. Am Tag 1 reicht Browser-Login oder XAI_API_KEY.

---

2.5 Im richtigen Ordner starten

Warum im Projektordner starten? Grok Build arbeitet relativ zum Working Directory (CWD). Im falschen Ordner „sieht“ der Agent die falschen Dateien – oder du reviewst Diffs im falschen Kontext.

Hilfreiche Launch-Varianten:

# interaktiv im aktuellen Ordner
grok

# explizites Projektverzeichnis
grok --cwd ~/projects/your-project

# erste Nachricht direkt mitschicken (wird zum ersten Turn)
grok "Erkläre die Projektstruktur in 10 Bullet Points. Ändere nichts."

# letzte Session fortsetzen
grok -c

# bestimmte Session fortsetzen
grok --resume <session-id>

Was du an Tag 1 nicht brauchst: --yolo / --always-approve, wilde Worktrees und MCP-Server. Die kommen, wenn Scope und Review sitzen (Kapitel 4–10, 13).

---

2.6 Erste Sitzung: die TUI in 60 Sekunden

Nach Auth siehst du die Fullscreen-TUI mit zwei Hauptbereichen:

Bereich	Rolle
Scrollback	Verlauf: deine Prompts, Antworten, Tool-Calls, Diffs, Tasks
Prompt	Eingabe unten – hier tippst du Aufträge und /-Commands

• Enter sendet die Nachricht.
• Tab wechselt den Fokus zwischen Prompt und Scrollback.
• Während ein Turn läuft: Esc bricht ab (Draft bleibt erhalten; Ausnahme: Fullscreen-Vim-Modus – dort Ctrl+C).
• Idle mit leerem Prompt: doppeltes Esc (innerhalb ~800 ms) öffnet Rewind; mit Text im Prompt löscht doppeltes Esc den Draft.

Details und Edge-Cases: Kapitel 3. Hier reicht: Prompt fokussieren, kurzen Auftrag senden, Tool-Ausgabe im Scrollback lesen.

---

2.7 Permissions am Tag 1: lesen, nicht wegklicken

Standardmäßig fragt Grok nach, bevor Shell-Befehle oder Datei-Edits laufen (Mode ask / default). Read-only-Tools und eingebaute harmlose Lese-Shell laufen oft ohne Prompt – der Rest will deine Zustimmung.

Was du im UI erwarten solltest: Bei riskanten Schritten erscheint ein Freigabe-Dialog (Wortlaut je Release: erlauben / einmal erlauben / ablehnen o. Ä.). Du siehst den geplanten Befehl oder die Datei-Änderung bevor etwas passiert. Bei Edits erscheint im Scrollback ein Diff-Block (+/−-Zeilen) – den expandierst du und liest, bevor du „passt“ denkst. Unsicher? Ablehnen ist der sichere Default, kein Scheitern.

Reaktion	Bedeutung
Einmal erlauben	Diese eine Aktion jetzt
Ablehnen	Nein – der Agent muss einen anderen Weg finden
Abbrechen (Esc / Ctrl+C je nach Zustand)	Stopp, du übernimmst

Anfänger-Regel: Bei Shell-Befehlen, die du nicht in einem Satz erklären kannst → ablehnen und nachfragen: „Erkläre den Befehl in einem Satz, ohne ihn auszuführen.“

Always-approve / YOLO (Ctrl+O, /always-approve, grok --yolo) brauchst du an Tag 1 nicht. Es spart Klicks und multipliziert Fehler. Für Automation später: Always-approve plus Deny-Regeln und Hooks (Kapitel 10 und 13).

Gefährliche Muster (ablehnen oder zumindest nachdenken):

• rm -rf und ähnliche Destruktiv-Shell
• curl … | bash / unbekannte Remote-Installer
• Lesen/Schreiben von .env und Secret-Pfaden
• git push --force / History umschreiben
• Unerwartete Netzwerk-Calls mit internen URLs

---

2.8 Drei sichere Aufgaben (ca. 15 Minuten)

Standard-Übungsrepo des Buchs: beispiele/todo-cli/ – klein, absichtlich unperfekt, mit fertiger AGENTS.md. Eigenes Side-Projekt geht auch; nicht Produktion, nicht der Downloads-Ordner mit dem fremden ZIP.

Nur PDF, kein Buch-Repo? Entweder ein kleines eigenes Side-Projekt nehmen oder das Buch-Repo clonen und die Übungen relativ zum Repo-Root fahren. Die Pfade beispiele/todo-cli gelten vom Root dieses Repos aus – nicht vom Home-Verzeichnis.

Setup todo-cli (einmal)

cd beispiele/todo-cli   # vom Root des Buch-Repos; sonst absoluten Pfad nutzen
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest -q
grok

Beim ersten Start ggf. Folder-Trust für Project-Hooks bestätigen (/hooks-trust bzw. Prompt) – Details später; am Tag 1 blockiert fehlendes Trust dich nicht am Erklären und kleinen Edits.

90 Sekunden: Terminal und Diff

Bevor Aufgabe B startet, reicht dieses Minimum:

pwd          # wo bin ich? (CWD = Arbeitsverzeichnis von grok)
ls           # was liegt hier?
git status   # optional: geänderte/untracked Dateien
git diff     # optional: Zeilen-Diff – + hinzugefügt, − entfernt

Kein Git im Übungsordner? Datei nach dem Edit mit Editor oder cat NOTES.md öffnen – der Review-Muskel zählt, nicht das Tool. CWD ist das Verzeichnis, in dem grok startet; im falschen Ordner sieht der Agent die falschen Dateien.

Aufgabe A – Code erklären lassen (ohne Edits)

Mit todo-cli:

Erkläre todo/store.py in einfachen Worten: was speichert die Datei, wie speichert sie?
Ändere noch nichts. Keine Shell außer lesenden Befehlen.

Mit eigenem Repo:

Erkläre die wichtigsten Einstiegspunkte dieses Repos in einfachen Worten.
Ändere noch nichts. Keine Shell außer lesenden Befehlen.

Was du beobachten solltest: Lesende Tools (read_file, grep, list_dir), eine Erklärung, keinen Edit-Diff. Wenn trotzdem geschrieben wird: abbrechen und den Prompt enger wiederholen.

Warum so formulieren? „Ändere noch nichts“ setzt den Erwartungshorizont. Grok kann schreiben – du willst erst verstehen.

Aufgabe B – kleine Datei erzeugen und selbst prüfen

Erstelle eine Datei NOTES.md mit genau drei Bullet-Points:
was das Projekt tut, wie man Tests startet, und eine offene Frage.
Keine anderen Dateien anfassen.

Danach selbst im Terminal (außerhalb oder mit ! in der TUI – Kapitel 3):

cat NOTES.md
# oder:
git diff

Warum manuell prüfen? Der Agent kann „fertig“ sagen und trotzdem den Scope verfehlen. Zehn Sekunden Review trainieren das Muskelgedächtnis für große Diffs.

Aufgabe C – Fehler erklären, noch nicht fixen

Wähle eine Variante:

Variante todo-cli / Python:

python3 -c "import missing_module_xyz"

Variante eigener Stack: Nimm einen echten Fehler aus CI oder lokal (komplette Meldung kopieren).

Variante ohne Traceback: Im Prompt beschreiben, was du erwartest vs. was passiert – und den Agenten nur erklären lassen, z. B. „Was würde fehlen, damit todo rm 1 funktioniert? Noch nichts implementieren.“

In der Session (bei Traceback):

Ich bekomme diesen Fehler:

[kompletten Traceback / Log hier einfügen]

Erkläre die Ursache und schlage einen minimalen Fix vor.
Den Fix noch nicht anwenden.

Warum erst erklären, dann fixen? Sonst springt der Agent in Edit-Loops, bevor die Diagnose sitzt. Wie du den Fehler übergibst: komplette Meldung – „geht nicht“ zwingt zum Raten und verbrennt Kontext.

---

2.9 Mini-Tour: Slash-Commands und @ am Tag 1

Slash-Commands steuern den Harness, nicht „das Modell umstimmen“. Tippe / im Prompt – es erscheint ein fuzzy Menü.

Command	Wofür an Tag 1
/session-info (Aliases /status, /info)	Modell, Auth, Kontext grob sehen
/context	Kontextfenster-Aufschlüsselung
/new / /clear	Frische Session
/resume	Alte Session laden
/compact	Kontext zusammendrücken (mit optionalem Hinweis, was behalten werden soll)
/doctor	Terminal/Session-Diagnose
/always-approve	Noch nicht für den Lern-Parcours
/quit / /exit	Beenden
/plan	ab Kapitel 4 – hier nur merken

Datei anhängen mit @:

# mit todo-cli
@todo/store.py erkläre Speichern und Laden. Ändere nichts.
@todo/store.py:1-40 was macht dieser Block?

# mit eigenem Repo
@src/main.ts erkläre diese Datei. Ändere nichts.

@ öffnet einen Fuzzy-Picker (respektiert .gitignore, versteckt Dotfiles). Mit ! auch versteckte Pfade: @!.env – vorsichtig (Secrets im Kontext).

---

2.10 Project Rules in einem Satz

Lege bei Bedarf eine kurze AGENTS.md ins Repo (oder global ~/.grok/AGENTS.md). Grok injiziert sie als Projekt-Anweisungen. Deeper paths gewinnen; CLAUDE.md wird kompatibilitätsweise mitgelesen. Ausführlich: Kapitel 7. Am Tag 1 reicht oft noch gar keine Datei – Scope im Prompt genügt.

Minimal-Vorlage: vorlagen/AGENTS.md.minimal.md.

---

2.11 Jetzt selbst machen: 15-Minuten-Parcours

Jetzt selbst machen

1. Installer ausführen und grok --version verifizieren.
2. grok doctor einmal laufen lassen; offensichtliche PATH-/Terminal-Findings notieren.
3. beispiele/todo-cli setuppen (oder eigenes bekanntes Repo) und grok starten; Auth abschließen.
4. Aufgabe A (nur erklären) – kein Diff.
5. Aufgabe B (NOTES.md) – danach git diff oder Datei lesen.
6. Aufgabe C (Fehler erklären) – kein Fix anwenden.
7. /session-info und /context einmal ansehen.
8. Session mit /quit beenden; optional grok -c testen.

Erfolg: Du hast mindestens einen erlaubten und einen abgelehnten Tool-Call bewusst erlebt – und einen Diff gelesen, bevor du „passt“ gesagt hast.

---

2.12 Häufige Fehler

Symptom	Typische Ursache	Erster Check
grok: command not found	PATH / Shell nicht neu gestartet	which grok, neue Terminal-Tab, Installer-Log
Login-Schleife / sofort wieder raus	Token abgelaufen, kaputte auth.json	grok logout && grok login
Key greift nicht	Session-Token hat Vorrang	grok logout, dann nur XAI_API_KEY
TUI ohne Farbe / kaputte Keys in tmux	Terminal-Capabilities	grok doctor, /doctor, Guide Terminal support
Agent schreibt, obwohl „nur erklären“	Prompt zu weich	Scope wiederholen, Turn abbrechen, engere Formulierung
Zu viele Permission-Prompts	Erwartetes ask-Verhalten	Nicht sofort YOLO – gezielte Allows und später Config (Kap. 13)
„Falsches Repo“	CWD falsch	pwd, grok --cwd …

Steckst du länger fest? Tabelle oben zuerst; später Symptom→Fix in Kapitel 16 (Abschnitt 16.6).

---

2.13 Checkliste First-Start

• grok --version zeigt eine Version
• grok doctor / /doctor ohne blockierende PATH-Fehler
• Auth (Browser oder Key) funktioniert
• Session im bekannten Übungsrepo, nicht in Produktion
• Mindestens ein Read-only-Auftrag ohne Edits
• Mindestens ein Edit mit manuellem Diff-Check
• Always-approve noch aus
• Keine Secrets in Prompts oder committeden Dateien

---

Was du jetzt kannst

• Grok Build installieren, updaten und mit grok --version / grok doctor verifizieren
• Browser-Login und API-Key-Auth unterscheiden und Credentials sicher behandeln
• Eine TUI-Session im richtigen CWD starten und drei sichere Aufgaben durchführen
• Permission-Prompts und die wichtigsten Day-1-Slash-Commands einordnen

Nächste Schritte

→ Kapitel 03 – Die interaktive TUI im Detail: Scrollback, Shortcuts, Modes, Queue und der tägliche Bedienrhythmus.