Getting Started

This page is the fastest path from a fresh install to a real, successful run.

1. Install Grok Code

Published install paths:

curl -fsSL https://grok.chaitanya.science/install.sh | sh

Other supported paths:

cargo install grok-cli
npm install -g grok-cli

Important:

• the published installer and npm package target Apple Silicon macOS
• if you are working from this repository, you can also build from source with cargo build --release -p grok-cli

2. Start The Product

Launch the TUI:

grok

If you prefer CLI-first setup, you can also authenticate without opening the TUI:

grok login
grok whoami

3. Connect xAI

Inside the TUI, open the guided setup flow:

/connect

The wizard walks you through:

• current readiness
• API key entry
• advanced settings such as region and response storage
• model and profile selection
• ready or repair state

If you already have a valid key, you can leave the API key field blank and keep the current one.

4. Choose How You Want To Work

Use The TUI If You Want

• guided setup and repair
• lane-based workflows such as Gate, Research, and Recall
• staged review before landing edits
• session continuity, bookmarks, handoffs, and export

Use grok run If You Want

• one human-readable result
• a single prompt from the shell
• edits applied live when the run succeeds

Example:

grok run "review the current diff for bugs"

Use grok exec If You Want

• CI- or script-friendly behavior
• progress on stderr
• final result on stdout
• optional JSONL events with --json

Examples:

grok exec "summarize the failing tests"
cat build.log | grok exec "explain this failure"
grok exec --json "run tests and summarize failures"

5. Verify Your Setup

Check the current auth and runtime defaults:

grok whoami

What you should expect:

• xAI should show as connected or usable
• the endpoint should match your region choice
• the selected model should match what you chose
• response storage should show on or off

If grok run or grok exec fail immediately with a missing credential error, finish xAI Auth And Setup.

6. First Success Ideas

Try one of these:

• in the TUI: ask for a repo walkthrough, open Research, or inspect Control
• with the CLI: grok run "summarize this repository"
• in a git repo: run a small task and compare the TUI Gate flow with live CLI edits

What Happens On Disk

Your first few runs usually create or populate:

• ~/.grok/config.toml
• ~/.grok/runtime/state.db
• .grok/ if you run grok init

The full storage map is in Configuration And Storage.