Skip to content

Configuration

Jump to bottom
Sagheer edited this page Dec 7, 2025 · 1 revision

Configuration Guide

Customize QuickCMD to match your workflow and security requirements.

📁 Configuration Files

QuickCMD uses YAML configuration files stored in ~/.quickcmd/:

~/.quickcmd/
├── config.yaml          # Main configuration
├── policy.yaml          # Security policies
├── audit.db             # Command history (SQLite)
└── plugins/             # Custom plugins

⚙️ Main Configuration (config.yaml)

Generate Default Config

quickcmd init

Full Configuration Example

# Execution Settings
default_mode: sandbox              # sandbox, direct, or dry-run
auto_approve_safe: true            # Auto-approve safe commands
sandbox_image: alpine:latest       # Docker image for sandbox

# Display Settings
show_confidence: true              # Show confidence scores
show_risk_level: true              # Show risk classification
enable_colors: true                # Colorized output
verbose: false                     # Verbose logging

# Learning Mode
enable_learning_mode: true         # Interactive explanations
show_tips: true                    # Show optimization tips
show_alternatives: true            # Show alternative commands

# History
max_history_entries: 10000         # Max history records
auto_export_history: false         # Auto-export on exit
history_export_format: csv         # csv, json, or sqlite

# Plugins
enabled_plugins:
  - git
  - kubernetes
  - aws
plugin_timeout: 30s                # Plugin execution timeout

# Remote Agents
default_agent: local               # Default execution target
agent_timeout: 60s                 # Remote agent timeout

# Web UI
web_port: 3000                     # Web interface port
web_enabled: false                 # Enable web UI
jwt_secret: "change-me"            # JWT secret for auth

# Analytics
enable_analytics: true             # Track usage patterns
enable_cost_estimation: true       # Show cost estimates
enable_time_prediction: true       # Predict execution time

# Notifications
slack_webhook: ""                  # Slack webhook URL
enable_notifications: false        # Enable notifications
notify_on_approval: true           # Notify on approval requests
notify_on_completion: false        # Notify on completion

🔒 Security Policy (policy.yaml)

Generate Default Policy

quickcmd policy init

Full Policy Example

# Denylist - Always blocked
denylist:
  - pattern: "rm -rf /"
    reason: "Prevents root deletion"
  
  - pattern: ":(){ :|:& };:"
    reason: "Prevents fork bomb"
  
  - pattern: "dd if=/dev/zero"
    reason: "Prevents disk wiping"
  
  - pattern: "mkfs\\..*"
    reason: "Prevents filesystem formatting"

# Allowlist - Always allowed (bypass other checks)
allowlist:
  - pattern: "^ls"
    reason: "List directory is safe"
  
  - pattern: "^cat"
    reason: "Read file is safe"
  
  - pattern: "^grep"
    reason: "Search is safe"
  
  - pattern: "^find.*-type f"
    reason: "Find files is safe"

# Approval Required - Needs team approval
approval_required:
  - pattern: "kubectl.*delete.*production"
    reason: "Production deletions need approval"
    approvers:
      - "admin@company.com"
      - "devops@company.com"
    min_approvals: 2
  
  - pattern: "aws.*delete.*production"
    reason: "AWS production changes need approval"
    approvers:
      - "admin@company.com"
    min_approvals: 1
  
  - pattern: "git push.*--force"
    reason: "Force push needs approval"
    approvers:
      - "senior-dev@company.com"
    min_approvals: 1

# Sandbox Required - Must run in sandbox
sandbox_required:
  - pattern: "rm.*-rf"
    reason: "Recursive delete must be sandboxed"
  
  - pattern: "docker.*rm.*-f"
    reason: "Force container removal must be sandboxed"

# Secrets Redaction
secrets:
  patterns:
    - "password"
    - "api[_-]?key"
    - "secret"
    - "token"
    - "credential"
  redact_in_logs: true
  redact_in_history: true

🔌 Plugin Configuration

Enable/Disable Plugins

# Enable plugin
quickcmd plugins enable git

# Disable plugin
quickcmd plugins disable aws

# List plugins
quickcmd plugins list

Plugin-Specific Config

Create ~/.quickcmd/plugins/git.yaml:

# Git Plugin Configuration
auto_backup: true                  # Auto-create backup branches
backup_prefix: "backup/"           # Backup branch prefix
max_backups: 10                    # Max backup branches

# Safety checks
prevent_force_push: true           # Block force push
warn_on_main: true                 # Warn when on main branch
require_approval_for_force: true   # Require approval for force operations

Create ~/.quickcmd/plugins/kubernetes.yaml:

# Kubernetes Plugin Configuration
default_namespace: default         # Default namespace
warn_on_production: true           # Warn for production operations
require_approval_for_delete: true  # Require approval for deletions

# Context awareness
auto_detect_context: true          # Auto-detect kubectl context
warn_on_context_switch: true       # Warn when switching contexts

🌐 Remote Agent Configuration

Agent Config (/etc/quickcmd/agent-config.yaml)

# Server Settings
port: 8443
tls_cert_file: "/etc/quickcmd/agent-cert.pem"
tls_key_file: "/etc/quickcmd/agent-key.pem"

# Authentication
hmac_secret: "your-secret-here"    # Generate with: openssl rand -hex 32
allowed_controllers:
  - "controller-1"
  - "https://quickcmd.example.com"

# Execution Limits
max_concurrent_jobs: 5
default_cpu_limit: 0.5             # CPU cores
default_memory_limit: 268435456    # 256 MB
default_timeout_seconds: 300       # 5 minutes

# Sandbox
allowed_images:
  - "alpine:latest"
  - "ubuntu:latest"
default_image: "alpine:latest"

Add Remote Agent

quickcmd remote add prod https://prod-server.com:8443 --token SECRET

💬 Slack Integration

Configure Slack

In config.yaml:

# Slack Settings
slack_webhook: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
slack_channel: "#devops"
enable_notifications: true
notify_on_approval: true
notify_on_high_risk: true

Test Slack Integration

quickcmd test slack

📊 Analytics Configuration

Enable Analytics

# Analytics
enable_analytics: true
enable_cost_estimation: true
enable_time_prediction: true
enable_risk_heatmap: true

# Cost Estimation
aws_region: us-east-1
cost_currency: USD

# Time Prediction
prediction_confidence_threshold: 0.7
min_samples_for_prediction: 5

🎨 Customization

Aliases

Create ~/.quickcmd/aliases.yaml:

aliases:
  deploy: "kubectl rollout restart deployment"
  logs: "kubectl logs -f deployment"
  pods: "kubectl get pods"
  backup: "tar -czf backup-$(date +%Y%m%d).tar.gz"

Macros

Create ~/.quickcmd/macros.yaml:

macros:
  safe-deploy:
    description: "Safe deployment with backup"
    steps:
      - command: "Create backup"
        continue_on_error: false
      - command: "Update deployment"
        continue_on_error: false
      - command: "Wait for rollout"
        continue_on_error: true
      - command: "Verify pods"
        continue_on_error: true

🔧 Environment Variables

Override config with environment variables:

export QUICKCMD_CONFIG=~/.quickcmd/config.yaml
export QUICKCMD_POLICY=~/.quickcmd/policy.yaml
export QUICKCMD_MODE=sandbox
export QUICKCMD_LOG_LEVEL=debug
export QUICKCMD_SANDBOX_IMAGE=ubuntu:latest

📝 Configuration Validation

Validate Config

# Validate main config
quickcmd config validate

# Validate policy
quickcmd policy validate

# Show current config
quickcmd config show

🚀 Best Practices

✅ Recommended Settings

# For Production
default_mode: sandbox
auto_approve_safe: false
enable_learning_mode: true
show_confidence: true
enable_analytics: true

🔒 Security Best Practices

  1. Always use sandbox for destructive operations
  2. Enable approval workflows for production
  3. Configure denylist for dangerous patterns
  4. Enable secrets redaction in logs
  5. Use HMAC authentication for remote agents
  6. Rotate JWT secrets regularly

🆘 Troubleshooting

Config Not Loading

# Check config location
quickcmd config path

# Validate syntax
quickcmd config validate

# Reset to defaults
quickcmd init --force

Policy Not Working

# Validate policy
quickcmd policy validate

# Test policy
quickcmd policy test "rm -rf /"

# Show active policy
quickcmd policy show

📚 Related Pages

Need help? Join our Discord!

Clone this wiki locally