A sophisticated CLI tool for interacting with xAI Grok 4, featuring conversation history, file reference, custom commands, memory system, and genetic development workflows
npm install @webdevtoday/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.
- 🤖 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
``bashInstall globally from npm
npm install -g @webdevtoday/grok-cli
$3
`bash
Initialize Grok CLI (prompts for API key and storage location)
grokOr 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 projectThe 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$3
`bash
Start interactive chat
grokContinue from last conversation
grok --continueResume specific conversation
grok --resume session-idUse development mode with OpenAI
grok --devEnable verbose logging
grok --verbose
`📖 Core Features
$3
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?
`$3
Automatic conversation persistence with powerful management:
`bash
List recent conversations
/history listSearch conversations
/history search "debugging"Continue from last session
grok --continueResume specific conversation
grok --resume abc123
`$3
Project-aware context management with GROK.md files:
`bash
Create project memory
/memory createAdd 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$3
Smart file discovery and reference:
`bash
Search for files
@package.json
@src/cli.tsSpecial commands
@recent # Recently modified files
@git # Git tracked files
@ext:ts # Files by extension
`$3
Define reusable workflows:
`bash
List custom commands
/custom listRun a command
/custom run setup-envInitialize genetic development commands
/init-commands
`$3
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 restrictionsPermission 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
$3
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 toolsUse MCP tools seamlessly
/mcp test github list_repositories '{"owner": "microsoft"}'
`$3
Event-driven automation:
`bash
Test hooks
/hooksConfiguration 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
$3
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 CLI2. 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 key3. Environment Variable:
`bash
export XAI_API_KEY="your-xai-api-key"
`
- Takes precedence over file-based API keys4. Command Line Flag:
`bash
grok --api-key your-xai-api-key
`
- Highest precedence, overrides all other methods$3
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/"]
}
}
`$3
Location:
.grok/settings.json`json
{
"hooks": {
"PreToolUse": [],
"PostToolUse": [],
"UserPromptSubmit": []
},
"permissions": {
"mode": "ask",
"allowedTools": [],
"disallowedTools": []
},
"mcp": {
"servers": {}
}
}
`📋 Command Reference
$3
| 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 |$3
| 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:
$3
`bash
Create tmux session with multiple agents
/custom run spawn-agentsMonitor agent activity
tmux lsJoin specific agent session
tmux attach -t agent-1
`$3
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
$3
`bash
Clone the repository
git clone https://github.com/webdevtodayjason/grok-cli.git
cd grok-cliInstall dependencies
npm installBuild the project
npm run buildLink for global usage
npm link
`$3
`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
$3
API Key Not Found
`bash
grok --api-key your-xai-api-key
`Permission Denied
`bash
Check permission mode
/permissions statusUpdate permissions
grok --permission-mode auto
`Memory Not Loading
`bash
Check memory status
/memory statusReload memory
/memory reload
`$3
`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`)This project is licensed under the MIT License - see the LICENSE file for details.
- 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