Grok CLI

A sophisticated CLI tool for interacting with xAI Grok 4, featuring conversation history, file reference, custom commands, memory system, and genetic development workflows.

✨ Features

• 🤖 AI Chat Interface - Interactive terminal chat with Grok 4
• 📚 Conversation History - Persistent chat history with search and continuation
• 🧠 Memory System - Persistent project context with automatic AI enhancement
• 📁 File Reference System - Smart file discovery and reference with @ commands
• 🔧 Custom Commands - User-defined workflows for genetic development
• 🪝 Hook System - Event-driven automation compatible with Claude Code patterns
• 🛠️ Tool Integration - Support for git, npm, python, docker, tmux, and more
• 🔌 MCP Integration - Full Model Context Protocol support for external tools
• 🔐 Enhanced Permission System - Advanced security with interactive prompts and audit logging
• 🎯 Multi-Agent Support - Tmux-based genetic development environments

🚀 Quick Start

Installation

# Install globally from npm
npm install -g @webdevtoday/grok-cli

# Or with yarn
yarn global add @webdevtoday/grok-cli

# Or with pnpm
pnpm add -g @webdevtoday/grok-cli

First Time Setup

# Initialize Grok CLI (prompts for API key and storage location)
grok

# Or provide API key directly
grok --api-key your-xai-api-key

API Key Storage Options:

During setup, you'll be asked where to store your API key:

• Global (~/.grok/api-key) - Available for all projects (recommended)
• Local (.grok-api) - Only for the current project

The CLI automatically checks for API keys in this priority order:

1. Command line --api-key flag
2. Environment variable XAI_API_KEY
3. Local project file .grok-api
4. Global user file ~/.grok/api-key

Basic Usage

# Start interactive chat
grok

# Continue from last conversation
grok --continue

# Resume specific conversation
grok --resume session-id

# Use development mode with OpenAI
grok --dev

# Enable verbose logging
grok --verbose

📖 Core Features

🤖 AI Chat Interface

Interactive terminal-based conversation with xAI Grok 4:

grok
You: Hello! Help me write a Python script
Grok: I'd be happy to help you write a Python script! What would you like the script to do?

📚 Conversation History

Automatic conversation persistence with powerful management:

# List recent conversations
/history list

# Search conversations
/history search "debugging"

# Continue from last session
grok --continue

# Resume specific conversation
grok --resume abc123

🧠 Memory System

Project-aware context management with GROK.md files:

# Create project memory
/memory create

# Add important context
/memory add "API uses JWT authentication"

# Search memory
/memory search "database"

# View memory status
/memory status

Memory files are automatically discovered and injected into conversations:

• ./GROK.md - Project-specific context
• ~/.grok-cli/GROK.md - User-level preferences
• Import system with @import directives

📁 File Reference System

Smart file discovery and reference:

# Search for files
@package.json
@src/cli.ts

# Special commands
@recent          # Recently modified files
@git             # Git tracked files
@ext:ts          # Files by extension

🔧 Custom Commands

Define reusable workflows:

# List custom commands
/custom list

# Run a command
/custom run setup-env

# Initialize genetic development commands
/init-commands

🔐 Enhanced Permission System

Advanced security with interactive prompts:

# Permission modes
grok --permission-mode ask    # Interactive prompts (default)
grok --permission-mode plan   # Show planned actions
grok --permission-mode auto   # Auto-approve all
grok --permission-mode full   # No restrictions

# Permission management
/permissions status           # Show system status
/permissions audit           # View security audit log
/permissions rules           # Show persistent rules
/permissions clear           # Clear session decisions

Security Features:

• Risk assessment with color-coded output
• Parameter sensitivity detection
• Persistent "Always/Never" rules
• Complete audit logging
• Session-based caching

🔌 MCP Integration

Full Model Context Protocol support:

# Add MCP servers
/mcp add github "npx @modelcontextprotocol/server-github" "--token=$GITHUB_TOKEN"
/mcp add filesystem "npx @modelcontextprotocol/server-filesystem" "/path/to/dir"

# Manage servers
/mcp list --verbose
/mcp status github
/mcp tools

# Use MCP tools seamlessly
/mcp test github list_repositories '{"owner": "microsoft"}'

🪝 Hook System

Event-driven automation:

# Test hooks
/hooks

# Configuration in .grok/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "echo 'About to execute tool'"
      }]
    }]
  }
}

🛠️ Tool Integration

Built-in support for development tools:

• Git - Repository management
• npm/yarn/pnpm - Package management
• Python/uv - Python environments
• Docker - Container management
• tmux - Multi-agent sessions
• MySQL/PostgreSQL - Database operations

⚙️ Configuration

API Key Management

Grok CLI supports multiple ways to configure your xAI API key:

1. Global API Key File (recommended):

   ~/.grok/api-key

   • Set during first-time setup by choosing "Global"
   • Available for all Grok CLI projects
   • Automatically loaded by the CLI

2. Local API Key File:

   .grok-api

   • Set during first-time setup by choosing "Local"
   • Only available for the current project
   • Automatically added to .gitignore
   • Takes precedence over global API key

3. Environment Variable:

   export XAI_API_KEY="your-xai-api-key"

   • Takes precedence over file-based API keys

4. Command Line Flag:

   grok --api-key your-xai-api-key

   • Highest precedence, overrides all other methods

Global Configuration

Location: ~/.grok/config.json

{
  "model": "grok-4",
  "apiKeys": {
    "xai": "your-api-key",
    "openai": "dev-api-key"
  },
  "permissions": {
    "mode": "ask",
    "allowedTools": [],
    "disallowedTools": []
  },
  "memory": {
    "autoLoad": true,
    "maxDepth": 5,
    "excludePatterns": ["node_modules/**", ".git/**"]
  }
}

Project Configuration

Location: .grok/settings.json

{
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [],
    "UserPromptSubmit": []
  },
  "permissions": {
    "mode": "ask",
    "allowedTools": [],
    "disallowedTools": []
  },
  "mcp": {
    "servers": {}
  }
}

📋 Command Reference

Slash Commands

| Command | Description | |---------|-------------| | /help | Show help message | | /status | System status | | /config | Show configuration | | /tools | List available tools | | /custom | Manage custom commands | | /history | Conversation history | | /memory | Memory management | | /mcp | MCP server management | | /permissions | Permission system management |

File Reference Commands

| Command | Description | |---------|-------------| | @filename | Search for files | | @path/to/file | Reference specific file | | @recent | Recently modified files | | @git | Git tracked files | | @ext:js | Files by extension |

🧬 Genetic Development

Grok CLI is designed for multi-agent genetic development workflows:

Multi-Agent Sessions

# Create tmux session with multiple agents
/custom run spawn-agents

# Monitor agent activity
tmux ls

# Join specific agent session
tmux attach -t agent-1

Example Genetic Workflow

1. Planning Agent - Analyzes requirements
2. Implementation Agent - Writes code
3. Testing Agent - Runs tests and validation
4. Review Agent - Code review and optimization

🔧 Development

Building from Source

# Clone the repository
git clone https://github.com/webdevtodayjason/grok-cli.git
cd grok-cli

# Install dependencies
npm install

# Build the project
npm run build

# Link for global usage
npm link

Scripts

npm run build         # Compile TypeScript
npm run dev           # Development mode
npm run test          # Run tests
npm run lint          # Lint code
npm run format        # Format code

🐛 Troubleshooting

Common Issues

API Key Not Found

grok --api-key your-xai-api-key

Permission Denied

# Check permission mode
/permissions status

# Update permissions
grok --permission-mode auto

Memory Not Loading

# Check memory status
/memory status

# Reload memory
/memory reload

Debug Mode

grok --debug --verbose

🤝 Contributing

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• xAI for the Grok 4 model
• Model Context Protocol for tool integration standards
• Claude Code for hook system inspiration

Made with ❤️ for the AI developer community