@webdevtoday/grok-cli/docs/custom-commands.md

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

# Custom Commands System

The Grok CLI includes a powerful custom commands system that allows you to create shortcuts for complex genetic development workflows.

## Overview

Custom commands let you:
- Create reusable shortcuts for complex command sequences
- Manage multi-agent development workflows
- Standardize team development processes
- Automate genetic algorithm testing and deployment

## Quick Start

### 1. Initialize Genetic Development Commands

```bash
# In the Grok CLI, run:
/init-commands
```

This adds predefined commands for genetic development:
- `genetic-test` - Run genetic algorithm test suite
- `multi-agent-start` - Start multi-agent development environment
- `genetic-build` - Build genetic algorithm components
- `agent-deploy` - Deploy agent to specified environment
- `data-pipeline` - Run genetic data processing pipeline

### 2. List Available Commands

```bash
/custom list
```

### 3. Run a Custom Command

```bash
/custom run genetic-test
```

## Command Structure

Custom commands are defined with the following structure:

```json
{
  "name": "command-name",
  "description": "What this command does",
  "command": "executable",
  "args": ["arg1", "arg2"],
  "cwd": "/optional/working/directory",
  "env": {
    "ENV_VAR": "value"
  },
  "timeout": 30000,
  "tags": ["tag1", "tag2"],
  "examples": ["Usage example"]
}
```

## Examples

### Genetic Algorithm Testing
```json
{
  "name": "genetic-test-full",
  "description": "Run complete genetic algorithm test suite with coverage",
  "command": "python",
  "args": ["-m", "pytest", "tests/genetic/", "--cov=genetic", "--cov-report=html"],
  "timeout": 120000,
  "tags": ["test", "genetic", "coverage"]
}
```

### Multi-Agent Session Management
```json
{
  "name": "spawn-agent",
  "description": "Create new agent session with tmux",
  "command": "tmux",
  "args": ["new-session", "-d", "-s", "agent-${RANDOM}"],
  "env": {
    "AGENT_ID": "${RANDOM}"
  },
  "tags": ["tmux", "agents"]
}
```

### Development Environment Setup
```json
{
  "name": "env-setup",
  "description": "Setup complete development environment",
  "command": "bash",
  "args": ["-c", "uv pip install -r requirements.txt && npm install && pre-commit install"],
  "timeout": 300000,
  "tags": ["setup", "environment"]
}
```

### Database Operations
```json
{
  "name": "db-migrate",
  "description": "Run database migrations",
  "command": "python",
  "args": ["manage.py", "migrate"],
  "cwd": "./backend",
  "env": {
    "DATABASE_URL": "postgresql://localhost/grok_dev"
  },
  "tags": ["database", "migration"]
}
```

## Advanced Usage

### Import/Export Commands

```bash
# Export your custom commands
/custom export /path/to/backup.json

# Import commands from file
/custom import /path/to/commands.json

# Import team commands
/custom import .grok/custom-commands-examples.json
```

### Command Categories by Tags

- **`genetic`** - Genetic algorithm specific commands
- **`agents`** - Multi-agent system commands
- **`tmux`** - Session management commands
- **`test`** - Testing and validation commands
- **`build`** - Compilation and build commands
- **`deploy`** - Deployment and distribution commands
- **`database`** - Database operations
- **`dev`** - Development environment commands

### Environment Variables

Commands can use environment variables for dynamic behavior:

```json
{
  "name": "deploy-to-env",
  "description": "Deploy to specified environment",
  "command": "python",
  "args": ["deploy.py", "--env", "${DEPLOY_ENV:-staging}"],
  "env": {
    "DEPLOY_ENV": "production"
  }
}
```

## Multi-Agent Workflows

Custom commands excel at managing multi-agent genetic development:

### 1. Agent Spawning
```bash
/custom run multi-agent-start
```

### 2. Distributed Testing
```bash
# Run tests across multiple agents
/custom run agent-test-suite
```

### 3. Coordinated Deployment
```bash
# Deploy to multiple environments
/custom run agent-deploy-all
```

## Integration with Tools

Custom commands work seamlessly with other Grok CLI tools:

- **Bash Tool**: Execute any command line tool
- **Tmux Tool**: Manage multi-agent sessions
- **Hook System**: Validate commands before execution
- **Permission System**: Control command access

## Best Practices

1. **Use Descriptive Names**: `genetic-test-coverage` vs `test`
2. **Add Tags**: Group related commands for easy discovery
3. **Set Timeouts**: Prevent hanging commands
4. **Use Working Directories**: Isolate command execution
5. **Environment Variables**: Make commands configurable
6. **Team Sharing**: Export/import commands for team consistency

## Example Workflow

```bash
# 1. Initialize project
/custom run env-setup

# 2. Start multi-agent environment
/custom run multi-agent-start

# 3. Run genetic algorithm tests
/custom run genetic-test

# 4. Build optimized components
/custom run genetic-build

# 5. Deploy agents
/custom run agent-deploy

# 6. Process data pipeline
/custom run data-pipeline
```

This creates a complete genetic development workflow that can be repeated consistently across different environments and team members.