Synopsis
Check configuration files for errors, warnings, and potential issues. Validates syntax, types, and values.
Usage
watercooler config validate [options]
Options
Project directory for config discovery. Defaults to current directory.
Treat warnings as errors (exit code 1 on any warning)
Examples
Validate current configuration
watercooler config validate
✓ Found: /home/user/.watercooler/config.toml
✓ Found: /path/to/project/.watercooler/config.toml
✓ Configuration is valid.
Validate with warnings
watercooler config validate
✓ Found: /home/user/.watercooler/config.toml
✓ Configuration is valid.
Warnings:
⚠ Port 80 requires root privileges.
⚠ fail_on_violation=true: Invalid entries will cause errors.
Strict validation
watercooler config validate --strict
✓ Found: /home/user/.watercooler/config.toml
✓ Configuration is valid.
Warnings:
⚠ Port 80 requires root privileges.
--strict: Treating warnings as errors.
Validation errors
watercooler config validate
✓ Found: /home/user/.watercooler/config.toml
Errors:
❌ Invalid port number: "abc" is not a valid integer
❌ Unknown transport type: "websocket" (must be "stdio" or "http")
Validate specific project
watercooler config validate --project-path ~/projects/myapp
No config files
watercooler config validate
Warnings:
⚠ No config files found. Using defaults.
✓ Configuration is valid.
Validation Checks
Syntax Validation
- Valid TOML syntax
- Proper section structure
- Quoted strings where required
- Valid data types
Type Validation
- Port numbers are integers
- Booleans are
true/false
- Paths are strings
- Enums match allowed values
Value Validation
- Port numbers in valid range (1-65535)
- Transport is
stdio or http
- Paths are accessible
- Required fields present
Semantic Validation
- Threads directory exists or can be created
- MCP port not in use (warning)
- Conflicting settings (warning)
Common Errors
Invalid TOML syntax
Error:
❌ TOML syntax error: Expected '=' after key at line 5
Invalid port
Error:
❌ Invalid port number: 99999 (must be 1-65535)
Invalid transport
Error:
❌ Unknown transport: "socket" (must be "stdio" or "http")
[mcp]
transport = "stdio" # or "http"
Type mismatch
Error:
❌ Type error: fail_on_violation must be boolean, got string
[validation]
fail_on_violation = true # not "true"
Common Warnings
Low port number
Warning:
⚠ Port 80 requires root privileges.
Strict validation enabled
Warning:
⚠ fail_on_violation=true: Invalid entries will cause errors.
[validation]
fail_on_violation = false
No config files
Warning:
⚠ No config files found. Using defaults.
watercooler config init --user
Exit Codes
| Code | Meaning |
|---|
| 0 | Valid configuration |
| 1 | Validation errors OR strict mode with warnings |
Workflows
Pre-deployment check
#!/bin/bash
set -e
watercooler config validate --strict
echo "Configuration valid, deploying..."
CI/CD integration
# .github/workflows/validate.yml
steps:
- name: Validate Watercooler config
run: watercooler config validate --strict --project-path .
Development validation
# Check config after editing
watercooler config validate
if [ $? -eq 0 ]; then
echo "✓ Config valid"
else
echo "✗ Config has errors"
fi
Interactive fixing
# Validate and show config if errors
if ! watercooler config validate; then
echo "Showing current config:"
watercooler config show
fi
