Grok CLI

![npm version](https://badge.fury.io/js/@webdevtoday%2Fgrok-cli)
![License: MIT](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

$3

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

$3

`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-keyflag 2. Environment variableXAI_API_KEY3. Local project file.grok-api4. Global user file~/.grok/api-key

`$3`

`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
$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 list
Search conversations

/history search "debugging"
Continue from last session

grok --continue
Resume specific conversation

grok --resume abc123


$3
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

`$3`

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


$3
Define reusable workflows:

`bash

`List custom commands`


/custom list
Run a command

/custom run setup-env
Initialize 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 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
$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 tools
Use MCP tools seamlessly

/mcp test github list_repositories '{"owner": "microsoft"}'


$3
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
$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 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

`$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-agents
Monitor agent activity

tmux ls
Join 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-cli
Install dependencies

npm install
Build the project

npm run build
Link 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 status
Update permissions

grok --permission-mode auto

Memory Not Loading`bash

`Check memory status`


/memory status
Reload 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`)
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

Grok CLI

![npm version](https://badge.fury.io/js/@webdevtoday%2Fgrok-cli)
![License: MIT](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

🚀 Quick Start

$3

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

$3

`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

`$3`

`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
$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 list
Search conversations

/history search "debugging"
Continue from last session

grok --continue
Resume specific conversation

grok --resume abc123


$3
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

`$3`

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


$3
Define reusable workflows:

`bash

`List custom commands`


/custom list
Run a command

/custom run setup-env
Initialize 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 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
$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 tools
Use MCP tools seamlessly

/mcp test github list_repositories '{"owner": "microsoft"}'


$3
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
$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 CLI

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

`$3`

Location: ~/.grok/config.json

`$3`

Location: .grok/settings.json

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

`📋 Command Reference`

`$3`

`🧬 Genetic Development`

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

`$3`

`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


$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-cli
Install dependencies

npm install
Build the project

npm run build
Link 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 status
Update permissions

grok --permission-mode auto

Memory Not Loading`bash

`Check memory status`


/memory status
Reload memory

/memory reload

$3

`bash grok --debug --verbose`

`🤝 Contributing`

📄 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