@webdevtoday/grok-cli

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:

• Command line --api-key flag
• Environment variable XAI_API_KEY
• Local project file .grok-api
• 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:

• 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

• 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

• Environment Variable:

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

  • Takes precedence over file-based API keys

• 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

• Planning Agent - Analyzes requirements
• Implementation Agent - Writes code
• Testing Agent - Runs tests and validation
• 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

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• 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