@webdevtoday/grok-cli/readme.md

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

# Grok CLI

[![npm version](https://badge.fury.io/js/@webdevtoday%2Fgrok-cli.svg)](https://badge.fury.io/js/@webdevtoday%2Fgrok-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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):
   ```bash
   ~/.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**:
   ```bash
   .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**:
   ```bash
   export XAI_API_KEY="your-xai-api-key"
   ```
   - Takes precedence over file-based API keys

4. **Command Line Flag**:
   ```bash
   grok --api-key your-xai-api-key
   ```
   - Highest precedence, overrides all other methods

### Global Configuration

Location: `~/.grok/config.json`

```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`

```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

```bash
# 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

```bash
# 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

```bash
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**
```bash
grok --api-key your-xai-api-key
```

**Permission Denied**
```bash
# Check permission mode
/permissions status

# Update permissions
grok --permission-mode auto
```

**Memory Not Loading**
```bash
# Check memory status
/memory status

# Reload memory
/memory reload
```

### Debug Mode

```bash
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](LICENSE) file for details.

## 🙏 Acknowledgments

- [xAI](https://xai.com/) for the Grok 4 model
- [Model Context Protocol](https://modelcontextprotocol.io/) for tool integration standards
- [Claude Code](https://claude.ai/code) for hook system inspiration

---

**Made with ❤️ for the AI developer community**