Skip to main content

​
Synopsis

Generate an annotated config.toml file from the built-in template. Creates either user-level or project-level configuration.

​
Usage

watercooler config init [options]

​
Options

​
--user
boolean
Create user-level config at ~/.watercooler/config.toml
​
--project
boolean
Create project-level config at .watercooler/config.toml in current directory
​
--force
boolean
Overwrite existing config file if it exists

​
Examples

​
Create user config

watercooler config init --user
Output: 
✅ Created user config: /home/username/.watercooler/config.toml
   Edit this file to customize Watercooler settings.

​
Create project config

watercooler config init --project
Output: 
✅ Created project config: /path/to/project/.watercooler/config.toml
   Edit this file to customize Watercooler settings.

​
Overwrite existing config

watercooler config init --user --force
Output: 
✅ Created user config: /home/username/.watercooler/config.toml
   Edit this file to customize Watercooler settings.

​
Default behavior (no flags)

watercooler config init
Defaults to user-level config (--user implied).

​
Configuration Levels

​
User Config (--user)

  • Location: ~/.watercooler/config.toml
  • Scope: All Watercooler projects for this user
  • Use for: Personal preferences, default agent settings, global MCP config

​
Project Config (--project)

  • Location: .watercooler/config.toml in project root
  • Scope: Specific project only
  • Use for: Project-specific threads directory, team settings, project agents

​
Configuration Priority

Settings are resolved in this order (highest priority first):
  1. Environment variables (e.g., WATERCOOLER_DIR)
  2. Project config (.watercooler/config.toml)
  3. User config (~/.watercooler/config.toml)
  4. Built-in defaults

​
Template Contents

The generated config file includes annotated sections for: 
# Watercooler Configuration

[paths]
threads_dir = "./watercooler"
code_root = "."

[agents]
default_agent = "Team"
default_role = "implementer"

[mcp]
transport = "stdio"  # or "http"
port = 3000

[validation]
fail_on_violation = false
strict_mode = false

# ... additional configuration options
Each section includes comments explaining:
  • Purpose of the setting
  • Valid values
  • Default behavior
  • Examples

​
Error Handling

​
Config already exists

watercooler config init --user
Output: 
❌ Config already exists: /home/username/.watercooler/config.toml
Use --force to overwrite.
Solution: Add --force flag to overwrite.

​
Template not found

If the built-in template is missing: 
❌ Template not found: /path/to/watercooler/templates/config.example.toml
This indicates a corrupted installation. Reinstall Watercooler: 
pip install --force-reinstall watercooler-cloud

​
Next Steps

After initialization:
  1. Edit the config: 
    # User config
$EDITOR ~/.watercooler/config.toml

# Project config
$EDITOR .watercooler/config.toml
  2. Validate configuration: 
    watercooler config validate
  3. View resolved settings: 
    watercooler config show

​
Common Configuration Patterns

​
Multi-project setup

# Set user defaults
watercooler config init --user
# Customize per-project
cd ~/project1 && watercooler config init --project
cd ~/project2 && watercooler config init --project

​
Team configuration

# Create project config for team
watercooler config init --project
# Commit to repository
git add .watercooler/config.toml
git commit -m "Add Watercooler config"

​
Fresh start

# Reset to defaults
watercooler config init --user --force

Build docs developers (and LLMs) love

Get started for freeTalk to us