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

@webdevtoday/grok-cli