Grok Code CLI

   ██████╗ ██████╗  ██████╗ ██╗  ██╗     ██████╗ ██████╗ ██████╗ ███████╗
  ██╔════╝ ██╔══██╗██╔═══██╗██║ ██╔╝    ██╔════╝██╔═══██╗██╔══██╗██╔════╝
  ██║  ███╗██████╔╝██║   ██║█████╔╝     ██║     ██║   ██║██║  ██║█████╗
  ██║   ██║██╔══██╗██║   ██║██╔═██╗     ██║     ██║   ██║██║  ██║██╔══╝
  ╚██████╔╝██║  ██║╚██████╔╝██║  ██╗    ╚██████╗╚██████╔╝██████╔╝███████╗
   ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝     ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝

A Production-Ready CLI Coding Assistant Powered by xAI's Grok Models

Installation · Features · Commands · Tools · Security · Contributing

What is Grok Code?

Grok Code is an agentic coding assistant that lives in your terminal. Think of it as having a senior developer pair programming with you - one that can read your files, write code, run commands, search the web, and help you build software faster.

$ grok

   ██████╗ ██████╗  ██████╗ ██╗  ██╗     ██████╗ ██████╗ ██████╗ ███████╗
  ██╔════╝ ██╔══██╗██╔═══██╗██║ ██╔╝    ██╔════╝██╔═══██╗██╔══██╗██╔════╝
  ██║  ███╗██████╔╝██║   ██║█████╔╝     ██║     ██║   ██║██║  ██║█████╗
  ██║   ██║██╔══██╗██║   ██║██╔═██╗     ██║     ██║   ██║██║  ██║██╔══╝
  ╚██████╔╝██║  ██║╚██████╔╝██║  ██╗    ╚██████╗╚██████╔╝██████╔╝███████╗
   ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝     ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝

╭──────────────────────────────────────────────────────────────────────╮
│  Grok Code CLI v0.1.0                                                │
│                                                                      │
│  Model:    grok-4-0709                                               │
│  CWD:      ~/myproject                                               │
│  Tools:    8 available (Read, Write, Edit, Bash, Glob, Grep, ...)    │
│                                                                      │
│  Commands: /help • /model • /doctor • exit                           │
╰──────────────────────────────────────────────────────────────────────╯

💡 Tip: Use /model to switch between Grok 4.1, Grok 4, and specialized models

❯ Help me create a REST API with Express

╭──────────────────────────────────────────────────────────────────────╮
│  🤖 Grok                                                              │
╰──────────────────────────────────────────────────────────────────────╯

I'll help you create a REST API with Express. Let me start by
checking your project structure and then create the necessary files.

┌─ 📖 Read ─────────────────────────────────────────────────────────────┐
│ Reading: package.json                                                  │
└────────────────────────────────────────────────────────────────────────┘

┌─ ✏️ Write ────────────────────────────────────────────────────────────┐
│ Creating: src/server.ts                                                │
│ Creating: src/routes/api.ts                                            │
└────────────────────────────────────────────────────────────────────────┘

┌─ ⚡ Bash ─────────────────────────────────────────────────────────────┐
│ $ npm install express                                                  │
└────────────────────────────────────────────────────────────────────────┘

✓ Created Express API with the following endpoints:
  GET  /api/users     - List all users
  POST /api/users     - Create a user
  GET  /api/users/:id - Get user by ID

❯ _

Why Grok Code?

Powered by Grok AI

Access xAI's latest models including Grok 4.1, Grok 4, and specialized models. Dynamic model fetching ensures you always have access to the newest models as they're released.

Production Ready

Built with TypeScript, comprehensive security hardening, and battle-tested on real projects. Not a toy - a real tool for real developers.

Claude Code Compatible

Familiar slash commands, permission system, and workflows. If you've used Claude Code, you'll feel right at home.

8 Powerful Tools

Read files, write code, execute commands, search codebases, fetch web content, and search the web - all with intelligent permission management.

Session Persistence

Resume conversations where you left off. Your context, history, and progress are automatically saved.

Extensible

Create custom slash commands for your team. Define project-specific workflows in .grok/commands/.

📸 Screenshots

Welcome Screen

The beautiful welcome screen shows your current model, working directory, and available tools:

   ██████╗ ██████╗  ██████╗ ██╗  ██╗     ██████╗ ██████╗ ██████╗ ███████╗
  ██╔════╝ ██╔══██╗██╔═══██╗██║ ██╔╝    ██╔════╝██╔═══██╗██╔══██╗██╔════╝
  ██║  ███╗██████╔╝██║   ██║█████╔╝     ██║     ██║   ██║██║  ██║█████╗
  ██║   ██║██╔══██╗██║   ██║██╔═██╗     ██║     ██║   ██║██║  ██║██╔══╝
  ╚██████╔╝██║  ██║╚██████╔╝██║  ██╗    ╚██████╗╚██████╔╝██████╔╝███████╗
   ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝     ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝

╭──────────────────────────────────────────────────────────────────────╮
│  Grok Code CLI v0.1.0                                                │
│                                                                      │
│  Model:    grok-4-0709                                               │
│  CWD:      /home/user/myproject                                      │
│  Tools:    8 available (Read, Write, Edit, Bash, Glob, Grep, ...)    │
│                                                                      │
│  Commands: /help • /model • /doctor • exit                           │
╰──────────────────────────────────────────────────────────────────────╯

💡 Tip: Use /compact to reduce context when conversations get long

❯ _

/help Command

Shows all 25+ available slash commands organized by category:

╭──────────────────────────────────────────────────────────────────────╮
│  📚 Grok Code CLI - Help                                              │
╰──────────────────────────────────────────────────────────────────────╯

  Session Management
  ─────────────────────────────────────────────────────────────────
    /clear              Clear conversation and start fresh
    /save, /s           Save current conversation
    /history            Show saved conversations
    /resume [id]        Resume a previous conversation
    /rename <name>      Rename current session
    /export [file]      Export conversation to file
    /compact [focus]    Reduce context size (keep last 20 messages)
    /exit, /q           Save and quit

  Configuration
  ─────────────────────────────────────────────────────────────────
    /config             Show current configuration
    /model [name]       Show or change the AI model
    /stream             Toggle streaming mode
    /permissions        View permission settings

  Status & Info
  ─────────────────────────────────────────────────────────────────
    /status             Show session status and info
    /context            Visualize context usage
    /cost               Show token usage and estimated cost
    /usage              Show usage statistics
    /doctor             Run diagnostics check
    /version            Show version

  ✓ 25+ slash commands available!

/model Command

Beautiful model selection with Grok 4.1 reasoning and fast variants:

╭──────────────────────────────────────────────────────────────────────╮
│  🤖 Model Selection                                                   │
╰──────────────────────────────────────────────────────────────────────╯

  Current Model: grok-4-0709

  ⭐ Grok 4.1 (Latest)
  ─────────────────────────────────────────────────────────────────
    🧠 grok-4-1-fast-reasoning [REASONING]
    ⚡ grok-4-1-fast-non-reasoning [FAST]

  🚀 Grok 4
  ─────────────────────────────────────────────────────────────────
    • grok-4-0709 ← current (recommended)
    🧠 grok-4-fast-reasoning [REASONING]
    ⚡ grok-4-fast-non-reasoning [FAST]

  📦 Grok 3
  ─────────────────────────────────────────────────────────────────
    • grok-3
    • grok-3-mini

  📷 Grok 2 (Vision/Image)
  ─────────────────────────────────────────────────────────────────
    • grok-2-image-1212
    • grok-2-vision-1212

  🔧 Specialized
  ─────────────────────────────────────────────────────────────────
    • grok-code-fast-1

  10 models available • Use /model <name> to switch
  🧠 = Reasoning (best for complex tasks) • ⚡ = Fast (quick responses)

/doctor Command

Comprehensive diagnostics to ensure everything is working:

╭──────────────────────────────────────────────────────────────────────╮
│  🩺 Grok Code CLI - Diagnostics                                       │
╰──────────────────────────────────────────────────────────────────────╯

  ✓ API Key          Configured
  ✓ Node.js          v18.19.1 (>=18 required)
  ✓ Working Dir      Read/write access OK
  ✓ Config Dir       /home/user/.config/grokcodecli
  ✓ Git              Available
  ✓ API Connection   Connected (10 models)

  All checks passed! Grok Code is ready to use.

Authentication Flow

Beautiful browser-based OAuth-like authentication:

╭──────────────────────────────────────────────────────────────────────╮
│  🔐 Grok Code CLI - Authentication                                    │
╰──────────────────────────────────────────────────────────────────────╯

  Welcome to Grok Code!

  To use Grok Code, you need an API key from xAI.
  We'll open your browser to the xAI console where you can:

    1. Sign in or create an account
    2. Go to API Keys section
    3. Create a new API key
    4. Copy the key and paste it here

❯ Open xAI Console in browser? [Y/n]: Y

  ⏳ Opening browser...
  ✓ Browser opened!

  ─────────────────────────────────────────────────────────────────
  Follow these steps in the browser:
  1. Sign in to your xAI account
  2. Click on "API Keys" in the sidebar
  3. Click "Create API Key"
  4. Copy the key (starts with "xai-")
  ─────────────────────────────────────────────────────────────────

❯ API Key: xai-••••••••••••••••••••

  ⠋ Validating API key...
  ✓ API key validated!

╭──────────────────────────────────────────────────────────────────────╮
│  🎉 Authentication Successful!                                        │
│                                                                      │
│  API Key:    ✓ Saved securely                                        │
│  Models:     10 available                                            │
│  Get started: grok                                                   │
╰──────────────────────────────────────────────────────────────────────╯

Tool Execution

Beautiful colored boxes show tool execution in real-time:

❯ Read the package.json file

╭──────────────────────────────────────────────────────────────────────╮
│  🤖 Grok                                                              │
╰──────────────────────────────────────────────────────────────────────╯

I'll read the package.json file for you.

┌─ 📖 Read ─────────────────────────────────────────────────────────────┐
│ Reading: package.json                                                  │
│ Lines: 1-35                                                            │
│ Size: 1.2KB                                                            │
└────────────────────────────────────────────────────────────────────────┘

Here's your package.json:
...

Quick Start

Installation

Option 1: Install from npm (Recommended)

npm install -g grokcodecli

Option 2: Install from Source

git clone https://github.com/singhpratech/grokcodeclix.git
cd grokcodeclix
npm install
npm run build
npm link

Setup

Quick Start (Recommended)

Just run the auth command - it will guide you through everything:

grok auth

This will:

1. Open your browser to xAI Console
2. Guide you through creating an API key
3. Validate and save your key securely

╭──────────────────────────────────────────────────────────────────────╮
│  🔐 Grok Code CLI - Authentication                                   │
╰──────────────────────────────────────────────────────────────────────╯

  Welcome to Grok Code!

  To use Grok Code, you need an API key from xAI.
  We'll open your browser to the xAI console where you can:

    1. Sign in or create an account
    2. Go to API Keys section
    3. Create a new API key
    4. Copy the key and paste it here

❯ Open xAI Console in browser? [Y/n]: Y

  ⏳ Opening browser...
  ✓ Browser opened!

  ─────────────────────────────────────────────────────────────────
  Follow these steps in the browser:
  1. Sign in to your xAI account
  2. Click on "API Keys" in the sidebar
  3. Click "Create API Key"
  4. Copy the key (starts with "xai-")
  ─────────────────────────────────────────────────────────────────

❯ API Key: xai-••••••••••••••••••••

  ✓ API key validated!

╭──────────────────────────────────────────────────────────────────────╮
│  🎉 Authentication Successful!                                       │
│                                                                      │
│  API Key:    ✓ Saved securely                                       │
│  Models:     10 available                                           │
│  Get started: grok                                                  │
╰──────────────────────────────────────────────────────────────────────╯

Alternative: Environment Variable

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export XAI_API_KEY=your_api_key_here

Start Coding

grok

That's it! You're ready to go.

Features

Core Capabilities

| Feature | Description | |---------|-------------| | Interactive AI Chat | Real-time conversation with Grok AI for coding assistance, debugging, and learning | | Streaming Responses | Token-by-token streaming for responsive, natural feedback | | 8 Powerful Tools | Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch - everything you need | | Permission System | Color-coded risk levels with granular session-based approvals | | Dynamic Model Support | Automatically fetches latest models from xAI API |

Session Management

| Feature | Description | |---------|-------------| | Persistent History | Auto-save conversations with full context preservation | | Resume Sessions | Pick up exactly where you left off with /resume | | Export Conversations | Save chats to markdown for documentation | | Context Visualization | Track token usage with visual progress bars |

Security Hardened

| Protection | What It Does | |------------|--------------| | Path Traversal Prevention | Blocks access to /etc/, /proc/, /sys/, /dev/ and ../ attacks | | Command Injection Protection | Validates and blocks dangerous command patterns | | SSRF Prevention | Blocks localhost, internal IPs, and non-HTTP protocols | | Sensitive File Detection | Warns when accessing .env, credentials, and secrets |

Developer Experience

| Feature | Description | |---------|-------------| | 25+ Slash Commands | Comprehensive command set for every workflow | | Custom Commands | Create your own commands in .grok/commands/ | | Syntax Highlighting | Beautiful code output with language detection | | Diagnostic Tools | /doctor command validates your entire setup | | Smart Model Matching | Type grok4 or grok 3 - we'll figure it out |

Dynamic Model Support

Grok Code automatically fetches the latest models from the xAI API. When xAI releases new models, they appear instantly in your CLI without any updates needed.

Current Models (Auto-Updated)

╭──────────────────────────────────────────────────────────────────────╮
│  🤖 Model Selection                                                   │
╰──────────────────────────────────────────────────────────────────────╯

  Current Model: grok-4-0709

  ⭐ Grok 4.1 (Latest)
  ─────────────────────────────────────────────────────────────────
    🧠 grok-4-1-fast-reasoning [REASONING]
    ⚡ grok-4-1-fast-non-reasoning [FAST]

  🚀 Grok 4
  ─────────────────────────────────────────────────────────────────
    • grok-4-0709 ← current (recommended)
    🧠 grok-4-fast-reasoning [REASONING]
    ⚡ grok-4-fast-non-reasoning [FAST]

  📦 Grok 3
  ─────────────────────────────────────────────────────────────────
    • grok-3
    • grok-3-mini

  📷 Grok 2 (Vision/Image)
  ─────────────────────────────────────────────────────────────────
    • grok-2-image-1212
    • grok-2-vision-1212

  🔧 Specialized
  ─────────────────────────────────────────────────────────────────
    • grok-code-fast-1

  10 models available • Use /model <name> to switch
  🧠 = Reasoning (best for complex tasks) • ⚡ = Fast (quick responses)

🧠 Reasoning Models: Recommended for complex coding tasks - they provide step-by-step thinking for better accuracy.

⚡ Fast Models: Great for quick responses and simpler tasks where speed matters more than deep analysis.

Smart Model Matching

You don't need to type exact model names. Grok Code uses intelligent matching:

| You Type | Matches | |----------|---------| | grok41 | grok-4-1-fast-non-reasoning | | grok 4 1 | grok-4-1-fast-non-reasoning | | grok4 | grok-4-0709 | | 4.1 | grok-4-1-fast-non-reasoning | | reasoning | grok-4-1-fast-reasoning | | vision | grok-2-vision-1212 | | code | grok-code-fast-1 | | mini | grok-3-mini |

# All of these work:
/model grok41        # → grok-4-1-fast-non-reasoning
/model grok4         # → grok-4-0709
/model reasoning     # → grok-4-1-fast-reasoning
/model vision        # → grok-2-vision-1212
/model code          # → grok-code-fast-1

Slash Commands

Grok Code includes 25+ built-in commands for every workflow:

Session Management

| Command | Alias | Description | |---------|-------|-------------| | /clear | /c | Clear conversation and start fresh | | /save | /s | Save current conversation | | /history | | Show saved conversations with timestamps | | /resume [id] | | Resume a previous conversation | | /rename <name> | | Rename current session | | /export [file] | | Export conversation to markdown file | | /compact [focus] | | Reduce context size (keep last 20 messages) | | /exit | /q | Save and quit |

Configuration

| Command | Description | |---------|-------------| | /config | Show current configuration settings | | /model [name] | Show available models or switch to a different model | | /stream | Toggle streaming mode on/off | | /permissions | View permission settings and risk levels |

Status & Diagnostics

| Command | Description | |---------|-------------| | /status | Show session status, model, uptime, and message count | | /context | Visualize context usage with progress bar | | /cost | Show token usage and estimated cost | | /usage | Show detailed usage statistics | | /doctor | Run comprehensive diagnostics check | | /version | Show Grok Code version |

Project Setup

| Command | Description | |---------|-------------| | /init | Initialize project with GROK.md configuration file | | /review [focus] | Request AI code review with optional focus area | | /terminal-setup | Show terminal configuration tips |

Working Directory

| Command | Description | |---------|-------------| | /add-dir <path> | Add a working directory to the session | | /pwd | Show current working directories |

Quick Reference

| Alias | Full Command | Description | |-------|--------------|-------------| | /h | /help | Show help | | /c | /clear | Clear conversation | | /s | /save | Save conversation | | /q | /exit | Quit | | exit | /exit | Quit (natural language) | | quit | /exit | Quit (natural language) |

Available Tools

Grok Code has access to 8 powerful tools that enable it to interact with your codebase and the web:

📖 Read Tool (Low Risk)

Read file contents with line numbers and intelligent handling.

Capabilities:
  ✓ Supports offset/limit for large files
  ✓ Detects and rejects binary files
  ✓ Line number formatting (like cat -n)
  ✓ Truncates very long lines (>2000 chars)

Limits:
  → Maximum file size: 10MB
  → Maximum lines returned: 2000

Example Usage:

You: Read the first 50 lines of src/index.ts
Grok: [Uses Read tool with limit: 50]

You: Show me lines 100-150 of the config file
Grok: [Uses Read tool with offset: 100, limit: 50]

✏️ Write Tool (Medium Risk)

Create or overwrite files with full content.

Capabilities:
  ✓ Auto-creates parent directories
  ✓ Shows size diff from previous version
  ✓ Reports line count and file size

Limits:
  → Maximum content size: 50MB

Security:
  ⚠️ Warns when writing to sensitive paths
  ⚠️ Blocked from system directories

Example Usage:

You: Create a new React component called Button
Grok: [Uses Write tool to create src/components/Button.tsx]
      ✓ File written: src/components/Button.tsx
        Lines: 45
        Size: 1.2KB

🔧 Edit Tool (Medium Risk)

Edit files by exact string replacement.

Capabilities:
  ✓ Precise string matching
  ✓ Prevents accidental multiple replacements
  ✓ Supports replace_all mode for bulk changes

Safety:
  → Requires exact string match
  → Fails if string appears multiple times (unless replace_all)
  → Shows before/after context

Example Usage:

You: Change the API endpoint from /api/v1 to /api/v2
Grok: [Uses Edit tool with old_string: "/api/v1", new_string: "/api/v2"]
      ✓ Edited src/config.ts
        Replaced 1 occurrence

⚡ Bash Tool (High Risk)

Execute shell commands with security validation.

Capabilities:
  ✓ Full bash shell access
  ✓ Captures stdout and stderr
  ✓ Configurable timeout (default: 2 minutes)
  ✓ Working directory support

Security:
  🛡️ Blocks dangerous patterns (rm -rf /, curl | sh, etc.)
  🛡️ Prevents privilege escalation
  🛡️ Validates commands before execution

Limits:
  → Maximum output: 1MB
  → Default timeout: 120 seconds
  → Maximum timeout: 10 minutes

Blocked Patterns:

✗ rm -rf /                    # Catastrophic deletion
✗ curl ... | sh               # Remote code execution
✗ wget ... | bash             # Remote code execution
✗ chmod 777                   # Dangerous permissions
✗ > /dev/sda                  # Device destruction
✗ :(){:|:&};:                 # Fork bombs

🔍 Glob Tool (Low Risk)

Find files matching patterns.

Capabilities:
  ✓ Full glob pattern support (*, **, ?, [])
  ✓ Recursive directory searching
  ✓ Sorted by modification time

Auto-Ignored:
  → node_modules/
  → .git/
  → dist/
  → build/
  → coverage/

Limits:
  → Maximum 100 results

Example Patterns:

**/*.ts           # All TypeScript files
src/**/*.test.js  # All test files in src
*.{js,ts}         # All JS and TS files in current dir

🔎 Grep Tool (Low Risk)

Search file contents with regex.

Capabilities:
  ✓ Full regex support (extended syntax)
  ✓ Case-sensitive and case-insensitive modes
  ✓ Context lines (before/after matches)
  ✓ 30+ file type filters

Limits:
  → Maximum 50 results
  → Respects .gitignore

Example Searches:

/TODO|FIXME/          # Find all TODOs
/function\s+\w+/      # Find function declarations
/import.*from/        # Find all imports

🌐 WebFetch Tool (Low Risk)

Fetch content from URLs.

Capabilities:
  ✓ HTML to readable text conversion
  ✓ JSON pretty printing
  ✓ Automatic content type detection
  ✓ Redirect following

Security:
  🛡️ SSRF protection (blocks localhost, internal IPs)
  🛡️ Only HTTP/HTTPS protocols allowed
  🛡️ Request timeout: 30 seconds

Limits:
  → Maximum response: 5MB

Blocked URLs:

✗ http://localhost:*          # Local services
✗ http://127.0.0.1:*          # Loopback
✗ http://192.168.*.*          # Private networks
✗ http://10.*.*.*             # Private networks
✗ file:///etc/passwd          # Local files

🔍 WebSearch Tool (Low Risk)

Search the web for information, documentation, tutorials, and more.

Capabilities:
  ✓ Real-time web search
  ✓ Returns titles, URLs, and snippets
  ✓ No API key required (uses DuckDuckGo)
  ✓ Sources section for citations

Limits:
  → Maximum 20 results
  → Query length: 500 characters

Example Usage:

You: Search for React hooks best practices
Grok: [Uses WebSearch tool]

🔍 Search Results for: "React hooks best practices"
Found 10 results

1. React Hooks Best Practices - Official Docs
   https://react.dev/reference/react
   Complete guide to React Hooks...

2. 10 React Hooks Best Practices
   https://blog.example.com/react-hooks
   Learn the most important patterns...

Sources:
  • [React Hooks Best Practices](https://react.dev/reference/react)
  • [10 React Hooks Best Practices](https://blog.example.com/react-hooks)

Permission System

Grok Code uses a granular permission system to keep you in control:

Permission Prompt

When Grok wants to use a tool, you'll see a beautifully formatted prompt:

╭─────────────────────────────────────────────────────────────────╮
│ ⚡ Permission Request: Bash                                     │
├─────────────────────────────────────────────────────────────────┤
│ Execute command: npm install express                            │
├─────────────────────────────────────────────────────────────────┤
│ command: npm install express                                    │
│ timeout: 120000                                                 │
╰─────────────────────────────────────────────────────────────────╯

  [y] Yes, allow once
  [a] Allow for this session
  [n] No, deny
  [!] Deny and block for session

Risk Levels

| Level | Icon | Color | Tools | Description | |-------|------|-------|-------|-------------| | Read | 📖 | Green | Read, Glob, Grep, WebFetch, WebSearch | Safe operations that only read data | | Write | ✏️ | Yellow | Write, Edit | Modifies files but reversible | | Execute | ⚡ | Red | Bash | Runs commands with system access |

Permission Responses

| Key | Action | Scope | |-----|--------|-------| | y | Allow | This request only | | a | Allow | All similar requests this session | | n | Deny | This request only | | ! | Block | All similar requests this session |

Auto-Approve Configuration

For trusted operations, you can configure auto-approval in your config:

{
  "autoApprove": ["Read", "Glob", "Grep"]
}

Custom Commands

Create your own slash commands as markdown files:

Project Commands (Shared with Team)

Create commands in .grok/commands/ in your project:

mkdir -p .grok/commands

.grok/commands/security.md

---
description: Review code for security vulnerabilities
---

Review this code for security issues including:
- SQL injection
- XSS vulnerabilities
- Authentication bypasses
- Sensitive data exposure

Focus on the most critical issues first.

Usage: /security

User Commands (Personal, All Projects)

Create commands in ~/.grok/commands/:

mkdir -p ~/.grok/commands

~/.grok/commands/explain.md

---
description: Explain code in detail
---

Explain this code in detail:
- What does each part do?
- Why was it written this way?
- Are there any potential issues?

Usage: /explain

Commands with Arguments

---
description: Fix a specific GitHub issue
argument-hint: <issue-number>
---

Fix GitHub issue #$ARGUMENTS following these guidelines:
1. Read the issue description
2. Understand the root cause
3. Implement the fix
4. Add tests if applicable
5. Update documentation if needed

Usage: /fix-issue 123

Command Priority

1. Project commands (.grok/commands/) - highest priority
2. User commands (~/.grok/commands/) - fallback

Security Features

Grok Code includes enterprise-grade security hardening:

Path Protection

Blocked Directories:
  ✗ /etc/           # System configuration
  ✗ /proc/          # Process information
  ✗ /sys/           # Kernel parameters
  ✗ /dev/           # Device files
  ✗ /boot/          # Boot files
  ✗ /root/          # Root home directory

Attack Prevention:
  ✗ ../../../etc/passwd    # Path traversal
  ✗ /home/user/../../../   # Directory escape

Sensitive File Detection

Warning Files (allowed with warning):
  ⚠️ .env                  # Environment variables
  ⚠️ .env.local            # Local environment
  ⚠️ credentials.json      # API credentials
  ⚠️ secrets.yaml          # Secret configuration
  ⚠️ id_rsa                # SSH private keys
  ⚠️ *.pem                 # Certificates

Command Protection

Blocked Patterns:
  ✗ rm -rf /              # Mass deletion
  ✗ rm -rf ~              # Home deletion
  ✗ rm -rf .              # Current dir deletion
  ✗ mkfs.*                # Filesystem formatting
  ✗ dd if=.* of=/dev/     # Device overwriting
  ✗ curl|sh, wget|bash    # Remote code execution
  ✗ chmod 777             # Dangerous permissions
  ✗ chown root            # Privilege escalation
  ✗ sudo su               # Root access

Network Protection (SSRF Prevention)

Blocked Hosts:
  ✗ localhost             # Local services
  ✗ 127.0.0.1             # Loopback IPv4
  ✗ ::1                   # Loopback IPv6
  ✗ 0.0.0.0               # All interfaces
  ✗ 192.168.*.*           # Private Class C
  ✗ 10.*.*.*              # Private Class A
  ✗ 172.16-31.*.*         # Private Class B
  ✗ 169.254.*.*           # Link-local

Blocked Protocols:
  ✗ file://               # Local files
  ✗ ftp://                # FTP
  ✗ gopher://             # Gopher
  ✗ data://               # Data URLs

Configuration

Config File Location

~/.config/grokcodecli/config.json

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | - | Your xAI API key | | model | string | grok-4-0709 | Default Grok model (reasoning recommended) | | temperature | number | 0.7 | Response creativity (0.0 - 1.0) | | maxTokens | number | 16384 | Maximum response tokens | | streaming | boolean | true | Enable token streaming | | autoApprove | string[] | [] | Tools to auto-approve |

Example Configuration

{
  "apiKey": "xai-your-api-key-here",
  "model": "grok-4-0709",
  "temperature": 0.7,
  "maxTokens": 16384,
  "streaming": true,
  "autoApprove": ["Read", "Glob", "Grep"]
}

Environment Variables

| Variable | Description | |----------|-------------| | XAI_API_KEY | Your xAI API key (overrides config) | | GROK_MODEL | Default model (overrides config) |

Session History

Storage Location

~/.config/grokcodecli/history/

What's Saved

Each session stores:

• Full conversation messages
• Tool call history
• Working directory
• Creation timestamp
• Last update timestamp
• Auto-generated title

Resume Commands

# Resume the most recent session
grok --resume

# Resume a specific session by ID
grok --resume abc123def

# List all saved sessions
grok
/history

Session Lifecycle

┌─────────────────┐
│   grok start    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  New Session    │───────┐
│  Created        │       │
└────────┬────────┘       │
         │                │
         ▼                │
┌─────────────────┐       │
│  Conversation   │◄──────┘
│  (auto-saved)   │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌───────┐ ┌───────┐
│/save  │ │/exit  │
│       │ │       │
└───┬───┘ └───┬───┘
    │         │
    ▼         ▼
┌─────────────────┐
│ Session Saved   │
│ ~/.config/...   │
└─────────────────┘
         │
         ▼
┌─────────────────┐
│ /resume or      │
│ grok --resume   │
└─────────────────┘

Diagnostics

Run /doctor to validate your setup:

🩺 Running diagnostics...

  ✓ API Key          API key is configured
  ✓ Node.js          v18.19.1 (>=18 required)
  ✓ Working Dir      Read/write access confirmed
  ✓ Config Dir       /home/user/.config/grokcodecli
  ✓ Git              Git is available
  ✓ API Connection   Connected to xAI API

  All checks passed! Grok Code is ready.

Diagnostic Checks

| Check | What It Validates | |-------|-------------------| | API Key | Key is configured and has correct format | | Node.js | Version 18.0.0 or higher | | Working Dir | Read/write access to current directory | | Config Dir | Config directory exists and is writable | | Git | Git is installed and accessible | | API Connection | Can reach xAI API and authenticate |

CLI Options

grok [options]

Options:
  -V, --version          Show version number
  -r, --resume [id]      Resume a previous session
  -m, --model <model>    Use a specific model
  -p, --prompt <text>    Start with an initial prompt
  -h, --help             Show help

Subcommands:
  grok auth              Configure API key
  grok config            Show configuration
  grok doctor            Run diagnostics

Examples

# Start a new session
grok

# Resume last session
grok --resume

# Start with a specific model
grok --model grok-4-0709

# Start with a prompt
grok --prompt "Help me refactor this function"

# Run diagnostics
grok doctor

Development

Building from Source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Development mode (watch)
npm run dev

# Link for local testing
npm link

Project Structure

grokcodeclix/
├── src/
│   ├── cli.ts                 # CLI entry point & argument parsing
│   ├── index.ts               # Public API exports
│   │
│   ├── grok/
│   │   └── client.ts          # xAI Grok API client
│   │
│   ├── conversation/
│   │   ├── chat.ts            # Main interactive loop (900+ lines)
│   │   └── history.ts         # Session persistence
│   │
│   ├── config/
│   │   └── manager.ts         # Configuration management
│   │
│   ├── permissions/
│   │   └── manager.ts         # Permission system
│   │
│   ├── tools/
│   │   ├── registry.ts        # Tool registration & execution
│   │   ├── read.ts            # File reading
│   │   ├── write.ts           # File writing
│   │   ├── edit.ts            # File editing
│   │   ├── bash.ts            # Command execution
│   │   ├── glob.ts            # File pattern matching
│   │   ├── grep.ts            # Content search
│   │   └── webfetch.ts        # HTTP requests
│   │
│   ├── utils/
│   │   ├── security.ts        # Security validation
│   │   └── ui.ts              # UI components
│   │
│   └── commands/
│       └── loader.ts          # Custom command loader
│
├── dist/                      # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Code Statistics

| Metric | Value | |--------|-------| | Total Lines | ~4,000 | | TypeScript Files | 16 | | Tools | 8 | | Slash Commands | 25+ | | Test Coverage | Growing |

Troubleshooting

Common Issues

"API key not configured"

# Set via environment variable
export XAI_API_KEY=your_key_here

# Or use auth command
grok auth

"Connection refused"

Check your network connection and ensure you can reach api.x.ai:

curl https://api.x.ai/v1/models -H "Authorization: Bearer $XAI_API_KEY"

"Permission denied"

# Ensure config directory is writable
chmod 755 ~/.config/grokcodecli

"Command not found: grok"

# If installed from source, link it
npm link

# Or add to PATH
export PATH="$PATH:$(npm prefix -g)/bin"

Comparison with Claude Code

| Feature | Grok Code | Claude Code | |---------|-----------|-------------| | AI Model | xAI Grok | Anthropic Claude | | Slash Commands | 25+ | 35+ | | Tools | 7 | 10+ | | Custom Commands | ✓ | ✓ | | Permission System | ✓ | ✓ | | Session Persistence | ✓ | ✓ | | Streaming | ✓ | ✓ | | Security Hardening | ✓ | ✓ | | MCP Support | Planned | ✓ | | IDE Integration | Planned | ✓ | | Cost | xAI pricing | Anthropic pricing |

Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Fork and clone
git clone https://github.com/YOUR_USERNAME/grokcodeclix.git
cd grokcodeclix

# Install dependencies
npm install

# Create a branch
git checkout -b feature/your-feature

# Make changes and test
npm run build
npm link
grok  # Test your changes

# Submit a PR
git push origin feature/your-feature

Contribution Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• Use TypeScript strict mode
• Follow existing patterns
• Add comments for complex logic
• Update documentation for new features

Roadmap

• [ ] MCP (Model Context Protocol) support
• [ ] IDE integrations (VS Code, JetBrains)
• [ ] Multi-file editing mode
• [ ] Git integration commands
• [ ] Image/vision support with Grok vision models
• [ ] Plugin system
• [ ] Team collaboration features

License

MIT License - see LICENSE for details.

MIT License

Copyright (c) 2024 Grok Code CLI Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Credits

Built with these amazing technologies:

| Technology | Purpose | |------------|---------| | xAI Grok API | AI models powering the assistant | | TypeScript | Type-safe development | | Node.js | Runtime environment | | Chalk | Beautiful terminal styling | | Commander.js | CLI framework | | Glob | File pattern matching |

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Contact maintainers

Built with Grok AI

Get Started · Documentation · Contribute

Made with determination by the Grok Code community