Installation

Complete installation guide for CLEO task management system

Installation Guide

This guide covers installation for both end users and contributors.

System Requirements

Operating System

Linux, macOS, or WSL2 on Windows

Bash

Version 4.0+ (installer auto-detects Homebrew Bash on macOS)

Disk Space

~10 MB for installation

For End Users

Option 1: One-liner (Easiest)

curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash

Reinstalling over existing installation? Use --force:

curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --force

Option 2: Download and Run

1. Download install.sh
2. Open Terminal and run:

# macOS/Linux: Run with bash (no chmod needed)
bash ~/Downloads/install.sh

The installer automatically detects missing dependencies (jq, flock) and offers to install them using your system’s package manager (apt, dnf, brew, pacman, apk).

Option 3: From Source (for Contributors)

git clone https://github.com/kryptobaseddev/cleo.git && cd cleo && ./installer/install.sh --dev

For Contributors

One-liner Install

curl -fsSL https://raw.githubusercontent.com/kryptobaseddev/cleo/main/installer/install.sh | bash

From Source

# Clone repository
git clone https://github.com/kryptobaseddev/cleo.git
cd cleo

# Install for development (creates symlinks to repo)
./installer/install.sh --dev

# Or install as release (copies files)
./installer/install.sh --release

Dev mode creates symlinks in ~/.local/bin/ pointing to your local repository. Changes to the repo are immediately reflected without reinstalling.

Release mode copies files to ~/.cleo/, creating an independent installation.

Installation Directory Structure

~/.cleo/
├── schemas/          # JSON Schema definitions
├── templates/        # Template files
├── scripts/          # Executable scripts
├── lib/              # Shared libraries
├── docs/             # Documentation
└── completions/      # Shell completions

Project Initialization

After global installation, initialize CLEO in each project:

cd /path/to/your/project
cleo init

This creates:

File	Purpose
.cleo/todo.json	Active tasks
.cleo/todo-archive.json	Completed tasks
.cleo/config.json	Project configuration
.cleo/todo-log.json	Audit trail

cleo init automatically injects task management instructions into CLAUDE.md, AGENTS.md, and GEMINI.md using {/* CLEO:START */} and {/* CLEO:END */} markers.

Prerequisites (Auto-Installed)

The installer will offer to install these if missing:

jq (JSON processor)

Required for JSON manipulation.

jq --version
# Should output: jq-1.5 or higher

Manual install if needed:

Ubuntu/Debian

sudo apt-get install jq

macOS

brew install jq

Fedora

sudo dnf install jq

flock (file locking)

Required for atomic file operations.

• Linux: Pre-installed (part of util-linux)
• macOS: brew install flock or brew install util-linux

Bash 4.0+

macOS ships with Bash 3.x. The installer auto-detects Homebrew Bash at:

• /opt/homebrew/bin/bash (Apple Silicon)
• /usr/local/bin/bash (Intel)

Install newer Bash:

brew install bash

Shell Completions

Enable tab completion for faster command entry:

Bash

Add to ~/.bashrc:

source ~/.cleo/completions/bash-completion.sh

Zsh

Add to ~/.zshrc:

fpath=(~/.cleo/completions $fpath)
autoload -Uz compinit && compinit

Migration from claude-todo

If you have existing claude-todo installations:

Check Status

cleo claude-migrate --check

Troubleshooting

Command Not Found

# Check symlink
ls -l ~/.local/bin/cleo

# Verify PATH includes ~/.local/bin
echo $PATH | grep ".local/bin"

# Add to PATH if missing (in ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# Reload shell
source ~/.bashrc

macOS Bash Version Error

If you see errors about Bash version:

# Install Homebrew Bash
brew install bash

# The installer will auto-detect it, or run explicitly:
/opt/homebrew/bin/bash ~/Downloads/install.sh

Validation Errors

# Check file integrity
cleo validate

# Attempt automatic fix
cleo validate --fix

# Restore from backup if needed
cleo restore

Permission Denied

# Fix script permissions
chmod +x ~/.cleo/scripts/*.sh

# Verify home directory is writable
touch ~/.cleo/test && rm ~/.cleo/test

Uninstallation

To remove CLEO completely:

# Remove global installation
rm -rf ~/.cleo

# Remove symlinks
rm ~/.local/bin/cleo ~/.local/bin/ct

# Remove project data (per project)
rm -rf .cleo/

This permanently deletes all task data. Create backups first with cleo backup.

Next Steps

Quick Start

Create your first task

Configuration

Customize CLEO for your workflow