---
title: Grok CLI
date: 2026-04-03 14:00:00
background: bg-[#7c3aed]
tags:
  - grok
  - xai
  - ai
  - cli
categories:
  - AI
intro: |
  [Grok CLI](https://www.grokcli.dev/docs/) is a conversational AI terminal tool powered by X.AI's Grok models, with file operations, code analysis, Plan Mode, and MCP support.
plugins:
  - copyCode
---

## Getting Started {.cols-3}

### Quick Start {.row-span-2}

```bash
# Run immediately (no install)
$ GROK_API_KEY=your_key npx -y grok-cli-hurry-mode@latest

# Install globally
$ npm install -g grok-cli-hurry-mode@latest

# Start interactive session
$ grok

# Send initial message
$ grok "Help me understand this project"

# Headless / non-interactive mode
$ grok -p "explain the auth module"

# Use a specific model
$ grok -m grok-4-latest "refactor this file"

# Set working directory
$ grok -d /path/to/project

# Set max tool rounds
$ grok --max-tool-rounds 100 "rewrite the API"
```

### Authentication

| Method        | How                                               |
| ------------- | ------------------------------------------------- |
| Env variable  | `export GROK_API_KEY=your_key`                    |
| Inline (npx)  | `GROK_API_KEY=key npx grok-cli-hurry-mode@latest` |
| CLI flag      | `grok --api-key your_key`                         |
| Settings file | Set `apiKey` in `~/.grok/user-settings.json`      |

Get your API key from [console.x.ai](https://console.x.ai).

Persist in shell profile:

```bash
echo 'export GROK_API_KEY=your_key' >> ~/.zshrc
source ~/.zshrc
```

### Installation Methods

| Method            | Command                                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| npm (recommended) | `npm install -g grok-cli-hurry-mode@latest`                                                           |
| npx (no install)  | `npx grok-cli-hurry-mode@latest`                                                                      |
| yarn              | `yarn global add grok-cli-hurry-mode@latest`                                                          |
| pnpm              | `pnpm add -g grok-cli-hurry-mode@latest`                                                              |
| bun               | `bun add -g grok-cli-hurry-mode@latest`                                                               |
| Auto script       | `curl -fsSL https://raw.githubusercontent.com/hinetapora/grok-cli-hurry-mode/main/install.sh \| bash` |

**Requirements:** Node.js (latest LTS), npm/yarn/pnpm, internet connection.

### AI Models

| Model              | Description                   |
| ------------------ | ----------------------------- |
| `grok-code-fast-1` | Default — optimized for code  |
| `grok-4-latest`    | Latest, enhanced capabilities |
| `grok-3-fast`      | Fast, general-purpose         |

Override with `-m`, `GROK_MODEL` env var, or `~/.grok/user-settings.json`.

Custom base URL: `-u https://api.x.ai/v1` or `GROK_BASE_URL`.

## CLI Options {.cols-2}

### All Options {.row-span-2}

| Option                  | Alias | Description                    |
| ----------------------- | ----- | ------------------------------ |
| `--api-key <key>`       | `-k`  | Grok API key                   |
| `--base-url <url>`      | `-u`  | API base URL                   |
| `--model <model>`       | `-m`  | Model to use                   |
| `--prompt <text>`       | `-p`  | Headless mode prompt           |
| `--directory <dir>`     | `-d`  | Set working directory          |
| `--max-tool-rounds <n>` |       | Max tool rounds (default: 400) |
| `--version`             | `-V`  | Show version                   |
| `--help`                | `-h`  | Show help                      |

**Environment variables:**

| Variable        | Purpose             |
| --------------- | ------------------- |
| `GROK_API_KEY`  | API key (required)  |
| `GROK_MODEL`    | Default model       |
| `GROK_BASE_URL` | Custom API endpoint |

### Subcommands

```bash
# AI-generated git commit and push
$ grok git commit-and-push
$ grok git commit-and-push -d /path/to/repo
$ grok git commit-and-push -m grok-4-latest

# MCP server management
$ grok mcp add <name>
$ grok mcp add-json <name> <json>
$ grok mcp remove <name>
$ grok mcp list
$ grok mcp test <name>
```

`git commit-and-push` accepts the same `-d`, `-k`, `-u`, `-m`, `--max-tool-rounds` flags as the main command.

## Interactive Mode {.cols-3}

### Keyboard Shortcuts {.row-span-2}

| Key               | Action                           |
| ----------------- | -------------------------------- |
| `Shift+Tab` twice | Enter Plan Mode                  |
| `Shift+Tab`       | Toggle auto-edit mode            |
| `Ctrl+I`          | Context tooltip (workspace info) |
| `Ctrl+C`          | Clear current input              |
| `Esc`             | Interrupt current operation      |
| `↑` / `↓`         | Browse input history             |

{.shortcuts}

**Auto-edit mode:** Hands-free file editing — the AI edits files without confirmation prompts.

**Context tooltip (`Ctrl+I`):** Shows project stats, git branch, memory pressure, and session info.

### Slash Commands

| Command              | Description                   |
| -------------------- | ----------------------------- |
| `/help`              | Show available commands       |
| `/clear`             | Clear terminal screen         |
| `/models`            | List available models         |
| `/exit`              | Quit the application          |
| `/compact`           | Compress conversation context |
| `/commit-and-push`   | AI commit message and push    |
| `/init-agent`        | Initialize agent docs         |
| `/docs`              | Open documentation            |
| `/readme`            | Generate README               |
| `/api-docs`          | Generate API docs             |
| `/changelog`         | Generate changelog            |
| `/comments`          | Add code comments             |
| `/update-agent-docs` | Update agent docs             |
| `/heal`              | Self-healing system check     |
| `/guardrails`        | Show guardrails status        |

### Config Files

| File                         | Purpose                |
| ---------------------------- | ---------------------- |
| `~/.grok/user-settings.json` | Global user settings   |
| `.grok/settings.json`        | Project-level settings |
| `.grok/GROK.md`              | Project context for AI |

**user-settings.json example:**

```json
{
  "apiKey": "your_api_key",
  "model": "grok-code-fast-1",
  "baseURL": "https://api.x.ai/v1"
}
```

**Create project context:**

```bash
# Add custom context for Plan Mode
$ mkdir -p .grok
$ echo "# Project Rules" > .grok/GROK.md
```

## Tools {.cols-3}

### Core Tools {.row-span-2}

| Tool      | Purpose                                    |
| --------- | ------------------------------------------ |
| **Read**  | Read files — text, images, PDFs, notebooks |
| **Write** | Create or overwrite files                  |
| **Edit**  | Precise string find-and-replace            |
| **Bash**  | Execute shell commands                     |
| **Grep**  | Regex search via ripgrep                   |
| **Glob**  | File pattern matching                      |
| **LS**    | Directory listing                          |

**Read** supports line offset/limit for large files and displays images visually.

**Edit** supports:

- Exact string replacement
- Regex patterns
- Single or all-occurrence replacement

**Bash** supports:

- stdout/stderr capture
- Background processes
- Timeout management
- Environment variable handling

### Advanced Tools

| Tool          | Purpose                               |
| ------------- | ------------------------------------- |
| **MultiEdit** | Atomic multi-file edits with rollback |
| **WebFetch**  | Retrieve and parse web content        |
| **WebSearch** | Real-time web search                  |
| **Task**      | Delegate to specialized sub-agents    |
| **TodoWrite** | Task tracking and progress            |

**MultiEdit** operations: create, edit, delete, rename, move — all in one atomic transaction.

**Task** (sub-agent delegation):

- Token-optimized processing
- Complex research and analysis
- Autonomous completion with report

**WebFetch:** HTML → Markdown conversion with AI content extraction and caching.

### IDE Tools

| Tool             | Purpose                          |
| ---------------- | -------------------------------- |
| **NotebookEdit** | Edit Jupyter notebook cells      |
| **BashOutput**   | Stream background process output |
| **KillBash**     | Terminate background processes   |

The AI **automatically selects** the right tool combination for your request — no manual invocation needed.

## Plan Mode {.cols-3}

### Activating Plan Mode {.row-span-2}

Press **`Shift+Tab` twice** in quick succession:

```
🎯 Plan Mode: Analysis
📊 Exploring codebase and gathering insights...
```

**Or use headless mode:**

```bash {.wrap}
$ grok -p "analyze changes in this PR and create plan"
$ grok -p "check if changes follow architecture guidelines"
```

**What is blocked in Plan Mode:**

- All file write/edit operations
- Destructive bash commands
- Any state-modifying operations

**What is allowed:**

- Reading files (`ls`, `cat`, `grep`)
- Web search and fetch
- Project structure analysis
- Plan generation (writes only to plan output)

**Exit Plan Mode:**

- `Enter` — confirm and execute the plan
- `Esc` — exit without executing

### Plan Mode Phases

| Phase           | Duration        | What Happens                     |
| --------------- | --------------- | -------------------------------- |
| 🔍 Analysis     | 1–5 sec         | Project type, structure, deps    |
| 🧠 Strategy     | 5–15 sec        | AI generates implementation plan |
| 📋 Presentation | 1–2 sec         | Format plan for review           |
| ✅ Approval     | User-controlled | Review, confirm, or refine       |

{.show-header}

Plan Mode analyzes: project type (Node/Python/React/etc.), directory structure, key components, dependencies, entry points, modules, and architectural patterns.

### Plan Mode Tips

Use Plan Mode for:

- Complex multi-file features
- Large-scale refactoring
- Exploring unfamiliar codebases
- Risk assessment before changes

**Tips:**

- Be specific about what you want
- Review the plan before approving
- Use `/heal` if something breaks
- Create `.grok/GROK.md` for custom context

## MCP Servers {.cols-2}

### Managing MCP Servers {.row-span-2}

```bash
# Add stdio server
$ grok mcp add myserver \
  -t stdio \
  -c npx \
  -a -y my-mcp-package

# Add HTTP/SSE server
$ grok mcp add myserver \
  -t http \
  -u https://api.example.com/mcp

# Add with env vars and headers
$ grok mcp add myserver \
  -t http \
  -u https://api.example.com/mcp \
  -e API_KEY=secret \
  -h Authorization="Bearer token"

# Add from raw JSON
$ grok mcp add-json myserver \
  '{"transport":{"type":"stdio","command":"npx","args":["-y","pkg"]}}'

# List all servers
$ grok mcp list

# Test connection
$ grok mcp test myserver

# Remove a server
$ grok mcp remove myserver
```

### MCP Config Schema

**In `.grok/settings.json`:**

```json
{
  "mcpServers": [
    {
      "name": "my-server",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "my-mcp-package"],
        "env": { "KEY": "value" }
      }
    },
    {
      "name": "remote-server",
      "transport": {
        "type": "http",
        "url": "https://api.example.com/mcp",
        "headers": { "Authorization": "Bearer $TOKEN" }
      }
    }
  ]
}
```

**Transport types:**

| Type              | When to Use                |
| ----------------- | -------------------------- |
| `stdio`           | Local subprocess (default) |
| `http`            | Remote HTTP endpoint       |
| `sse`             | Server-Sent Events         |
| `streamable_http` | Streaming HTTP             |

### Add Server Options

| Option               | Alias | Description                          |
| -------------------- | ----- | ------------------------------------ |
| `--transport <type>` | `-t`  | stdio / http / sse / streamable_http |
| `--command <cmd>`    | `-c`  | Executable (stdio only)              |
| `--args [args...]`   | `-a`  | Command arguments (stdio only)       |
| `--url <url>`        | `-u`  | Server URL (http/sse)                |
| `--headers [kv...]`  | `-h`  | HTTP headers (`key=value`)           |
| `--env [kv...]`      | `-e`  | Env vars (`key=value`)               |

## Troubleshooting {.cols-3}

### Common Issues {.row-span-2}

**API key not found:**

```bash
# Verify env var is set
$ echo $GROK_API_KEY

# Or set inline
$ GROK_API_KEY=key grok "hello"
```

**Command not found after install:**

```bash {.wrap}
# Add npm global bin to PATH
$ echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc
$ which grok
```

**Permission errors on install:**

```bash
# Use sudo (not recommended) or node version manager
$ npm install -g grok-cli-hurry-mode --force

# Or use nvm/fnm without sudo
$ nvm use --lts
$ npm install -g grok-cli-hurry-mode
```

**Stuck / cached installation:**

```bash
$ pkill -f grok
$ npm uninstall -g grok-cli-hurry-mode
$ npm cache clean --force
$ npm install -g grok-cli-hurry-mode@latest
```

### Useful Env Vars

| Variable        | Description            |
| --------------- | ---------------------- |
| `GROK_API_KEY`  | API key (required)     |
| `GROK_MODEL`    | Override default model |
| `GROK_BASE_URL` | Custom API endpoint    |

**Default API endpoint:** `https://api.x.ai/v1`

### Git Smart Push

The automated release system creates version bump commits, so always use smart push to avoid conflicts:

```bash
# Correct — handles auto version bumps
$ npm run smart-push
$ git pushup

# Wrong — causes "fetch first" errors
$ git push origin main
```

## Also see {.cols-1}

- [Official Documentation](https://www.grokcli.dev/docs/) _(grokcli.dev)_
- [Plan Mode Guide](https://www.grokcli.dev/docs/guides/plan-mode) _(grokcli.dev)_
- [Tools Overview](https://www.grokcli.dev/docs/tools/overview) _(grokcli.dev)_
- [Architecture Overview](https://www.grokcli.dev/docs/architecture/overview) _(grokcli.dev)_
- [GitHub Repository](https://github.com/hinetapora/grok-cli-hurry-mode) _(github.com)_
- [xAI API Console](https://console.x.ai) _(console.x.ai)_