Configuration

Configure CLEO behavior with config.json and environment variables

Configuration

CLEO supports project-level and global configuration through config.json and environment variables.

Configuration Hierarchy

Settings are resolved in order (highest priority first):

1. Command-line flags
2. Environment variables
3. Project config (.cleo/config.json)
4. Global config (~/.cleo/config.json)
5. Built-in defaults

Managing Configuration

# View all settings
cleo config show

# Get specific value
cleo config get archive.daysUntilArchive

# Set value
cleo config set archive.daysUntilArchive 14

# Set nested value
cleo config set hierarchy.maxSiblings 10

# Reset to default
cleo config unset archive.daysUntilArchive

Configuration Options

Archive Settings

archive.daysUntilArchive · number · default: "7"

Days after completion before auto-archiving tasks

archive.preserveRecentCount · number · default: "3"

Number of recent completed tasks to preserve from archiving

archive.autoArchive · boolean · default: "true"

Enable automatic archiving of old completed tasks

Validation Settings

validation.maxActiveTasks · number · default: "1"

Maximum number of tasks with active status (single-task discipline)

validation.requireDescription · boolean · default: "false"

Require description field when creating tasks

validation.maxTitleLength · number · default: "200"

Maximum length for task titles

validation.strict · boolean · default: "true"

Enable strict validation mode (more checks)

Hierarchy Settings

hierarchy.maxDepth · number · default: "3"

Maximum hierarchy depth (epic → task → subtask)

hierarchy.maxSiblings · number · default: "7"

Maximum children per parent task (0 = unlimited)

hierarchy.autoCompleteParent · boolean · default: "true"

Automatically complete parent when all children are done

hierarchy.autoCompleteMode · string · default: "auto"

Mode for auto-complete: auto, suggest, or off

Default Values

defaults.priority · string · default: "medium"

Default priority for new tasks

defaults.phase · string · default: "core"

Default phase for new tasks

defaults.status · string · default: "pending"

Default status for new tasks

Context Alerts

contextAlerts.enabled · boolean · default: "true"

Enable automatic context usage alerts

contextAlerts.warningThreshold · number · default: "70"

Percentage threshold for warning alerts

contextAlerts.cautionThreshold · number · default: "85"

Percentage threshold for caution alerts

contextAlerts.criticalThreshold · number · default: "90"

Percentage threshold for critical alerts

contextAlerts.emergencyThreshold · number · default: "95"

Percentage threshold for emergency alerts

Analyze Settings

analyze.sizeStrategy · string · default: "balanced"

Task size weighting: quick-wins (favor small), big-impact (favor large), or balanced

Environment Variables

Environment variables override config file settings:

Variable	Config Equivalent
CLEO_HOME	Installation directory
CLEO_PROJECT	Project data directory
CLEO_NO_COLOR	Disable colored output
CLEO_DEBUG	Enable debug logging
CLEO_MAX_ACTIVE	validation.maxActiveTasks
NO_COLOR	Standard color disable

# Example usage
CLEO_DEBUG=1 cleo add "Task with debug"
CLEO_MAX_ACTIVE=3 cleo focus set T001

Example Configuration

Project Config (.cleo/config.json)

{
  "_meta": {
    "schemaVersion": "1.2.0"
  },
  "archive": {
    "daysUntilArchive": 14,
    "preserveRecentCount": 5
  },
  "validation": {
    "maxActiveTasks": 1,
    "requireDescription": true
  },
  "hierarchy": {
    "maxDepth": 3,
    "maxSiblings": 10,
    "autoCompleteParent": true
  },
  "defaults": {
    "priority": "medium",
    "phase": "core"
  },
  "contextAlerts": {
    "enabled": true,
    "warningThreshold": 70
  }
}

Configuration Validation

# Validate configuration
cleo config validate

# Show effective config (merged from all sources)
cleo config show --effective

Best Practices

Use Project Config

Keep project-specific settings in .cleo/config.json for team consistency

Commit Config

Add .cleo/config.json to version control for reproducibility

Use Env Vars for Overrides

Use environment variables for temporary or CI/CD overrides

Validate After Changes

Run cleo config validate after modifying config

Next Steps

Schema Reference

Data structure documentation

Exit Codes

CLI exit code reference