@cleocode/cleo

CLEO CLI — the assembled product consuming @cleocode/core.

Overview

This is the main CLEO package that brings together all other packages into a unified command-line interface. It provides:

• CLI: 100+ commands for task management, sessions, memory, orchestration, and more
• Dispatch Layer: CQRS routing with query/mutate gateways, middleware pipeline, and LAFS envelope formatting
• Admin Tools: Configuration, backup, migration, and system management

The CLI is a thin wrapper — all business logic lives in @cleocode/core.

Installation

Global Installation (Recommended)

Important: As of v2026.4.109, @cleocode/core is now a peer dependency. Both packages must be installed:

npm install -g @cleocode/cleo @cleocode/core

To upgrade from a pre-v2026.4.109 installation, run:

npm install -g @cleocode/core

The postinstall hook in @cleocode/cleo will detect and warn if @cleocode/core is missing.

Local Installation

For local project-level installs, use the same two-package approach:

npm install @cleocode/cleo @cleocode/core

Workspace / pnpm Monorepo

If your project uses pnpm workspaces, dependency resolution is automatic via the workspace protocol. No additional installation steps are needed.

Batteries-Included (CleoOS)

npm install -g @cleocode/cleo-os

This installs cleo, ct, and cleoos binaries with CANT bridge and TUI extensions. CleoOS automatically includes @cleocode/core via its dependencies.

Using npx (No Installation)

npx @cleocode/cleo <command>

Note: npx does not install global packages and is best for one-off commands.

Quick Start

Initialize CLEO in Your Project

cd my-project
cleo init

Basic Commands

# Add a task
cleo add "Implement user authentication" --priority high --acceptance "AC1|AC2|AC3"

# Search tasks (returns readiness info: depends, type, size)
cleo find "auth" --status pending

# Start a work session
cleo session start --scope global --name "Auth Feature"

# Show current context
cleo current

# Complete a task
cleo complete T001

# Get help
cleo --help
cleo <command> --help

CLI Commands

CLEO provides 100+ commands organized into domains:

Task Management

| Command | Description | |---------|-------------| | cleo add <title> | Create a new task | | cleo add-batch --file tasks.json | Batch create tasks from JSON | | cleo list | List all tasks | | cleo show <id> | Show task details | | cleo find <query> | Search tasks (agent-optimized, includes readiness) | | cleo find <query> --verbose | Search with full task fields | | cleo find <query> --fields labels,acceptance | Search with specific extra fields | | cleo complete <id> | Mark task as complete | | cleo update <id> | Update task properties | | cleo delete <id> | Delete a task | | cleo start <id> | Start working on a task | | cleo stop | Stop current task | | cleo current | Show current task | | cleo next | Get next task to work on | | cleo archive <ids...> | Archive completed tasks | | cleo deps <id> | Show task dependencies | | cleo tree <id> | Show task tree | | cleo labels | Manage labels | | cleo blockers | Show blockers | | cleo stats | Task statistics | | cleo history <id> | Task history | | cleo reorder <id> <position> | Reorder tasks | | cleo reparent <id> <parent> | Change parent task | | cleo relates <id> <target> | Add relation | | cleo exists <id> | Check if task exists | | cleo promote <id> | Promote task to root level |

Session Management

| Command | Description | |---------|-------------| | cleo session start [--scope] [--name] | Start a new session | | cleo session list | List sessions | | cleo session resume <id> | Resume a session | | cleo session end [id] | End current session | | cleo briefing | Generate session briefing | | cleo phase | Phase management | | cleo checkpoint | Create checkpoint | | cleo safestop | Safe stop with context |

Memory & Context

| Command | Description | |---------|-------------| | cleo memory | Memory operations | | cleo memory-brain | Brain memory search | | cleo observe <text> | Save observation to brain.db | | cleo context | Show context | | cleo inject | Inject context | | cleo sync | Sync memory | | cleo sticky | Sticky notes | | cleo refresh-memory | Refresh memory bridge |

Validation & Compliance

| Command | Description | |---------|-------------| | cleo validate | Validate tasks | | cleo verify | Verify compliance | | cleo compliance | Compliance checks | | cleo doctor | System health check | | cleo analyze | Analyze project |

Pipeline & Lifecycle

| Command | Description | |---------|-------------| | cleo release | Release management | | cleo lifecycle | Lifecycle operations | | cleo promote <id> | Promote task/stage | | cleo upgrade | Upgrade CLEO | | cleo roadmap | Roadmap planning | | cleo plan | Create plan | | cleo phases | Phase operations | | cleo log | View logs | | cleo issue | Issue management | | cleo add --kind bug --severity Px | Bug tracking (ADR-066) |

Orchestration

| Command | Description | |---------|-------------| | cleo orchestrate | Orchestration operations | | cleo ops | Operations dashboard | | cleo consensus | Consensus workflow | | cleo contribution | Track contribution | | cleo decomposition | Decompose tasks | | cleo implementation | Implementation guide | | cleo sequence | Task sequencing | | cleo dash | Dashboard |

Nexus & Sync

| Command | Description | |---------|-------------| | cleo nexus | Nexus operations | | cleo init | Initialize project | | cleo remote | Remote management | | cleo push | Push to remote | | cleo pull | Pull from remote | | cleo snapshot | Create snapshot | | cleo export | Export data | | cleo import | Import data |

Administration

| Command | Description | |---------|-------------| | cleo config | Configuration | | cleo backup | Backup data | | cleo backup export | Pack a portable .cleobundle.tar.gz | | cleo backup import | Restore from a portable bundle | | cleo backup inspect | Print bundle manifest | | cleo restore finalize | Apply resolved conflicts | | cleo skills | Skills management | | cleo self-update | Update CLEO | | cleo grade | Grade session | | cleo migrate | Run migrations | | cleo adr | ADR management | | cleo map | Codebase map | | cleo commands | List all commands | | cleo otel | OpenTelemetry | | cleo token | Token management |

Cross-machine Backup (v2026.4.13+)

cleo backup export <name> [--scope project|global|all] [--encrypt]
cleo backup import <bundle> [--force]
cleo backup inspect <bundle>
cleo restore finalize

See ADR-038 for the full specification.

Global Options

# Output format
cleo --json <command>      # JSON output
cleo --human <command>     # Human-readable output (default)
cleo --quiet <command>     # Minimal output

# Field extraction
cleo --field <name> <command>     # Extract single field
cleo --fields <names> <command>   # Extract multiple fields

# Minimum viable information
cleo --mvi <level> <command>      # Control detail level

Configuration

Environment Variables

export CLEO_LOG_LEVEL=debug
export CLEO_PROJECT_ROOT=/path/to/project   # Override cwd-based project detection
export CLEO_ROOT=/path/to/project           # Alias for CLEO_PROJECT_ROOT

Configuration File

// .cleo/config.json
{
  "logging": { "level": "info" },
  "session": { "enforcement": { "requiredForMutate": true } },
  "lifecycle": { "mode": "advisory" },
  "enforcement": {
    "acceptance": { "mode": "block", "minimumCriteria": 3 }
  }
}

CLI Config Commands

cleo config set logging.level debug
cleo config get logging.level
cleo config list

Programmatic Usage

While the CLI is the primary interface, you can use the core SDK directly:

import { Cleo } from '@cleocode/core';

const cleo = await Cleo.init('./my-project');

// Task operations
await cleo.tasks.add({ title: 'New task' });

// Cleanup
await cleo.destroy();

Architecture

┌─────────────────────────────────────┐
│        @cleocode/cleo               │
│  ┌──────────────────────────────┐   │
│  │          CLI Layer           │   │
│  │  89 commands (commander.js)  │   │
│  └──────────────┬───────────────┘   │
│                 │                    │
│  ┌──────────────┴───────────────┐   │
│  │       Dispatch Layer         │   │
│  │  CQRS query/mutate routing   │   │
│  │  12 domain handlers          │   │
│  │  19 engine wrappers          │   │
│  │  Middleware pipeline          │   │
│  └──────────────┬───────────────┘   │
│                 │                    │
│  ┌──────────────┴───────────────┐   │
│  │       @cleocode/core         │   │
│  │  Tasks • Sessions • Memory   │   │
│  │  Orchestration • Lifecycle   │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘

Troubleshooting

Common Issues

"Project not initialized"

cleo init

"Storage migration needed"

cleo upgrade

"Permission denied"

chmod +x $(which cleo)

Debug Mode

export CLEO_LOG_LEVEL=debug
cleo <command>

Getting Help

cleo --help
cleo <command> --help
cleo doctor
cleo commands

Dependencies

Production

• @cleocode/core — Business logic SDK
• @cleocode/contracts — Shared type definitions
• @cleocode/caamp — Provider registry
• @cleocode/cant — CANT protocol parser
• @cleocode/lafs — Error envelope protocol
• @cleocode/runtime — Long-running process layer
• drizzle-orm — Database ORM
• pino — Logging

Binaries

• cleo — Primary command
• ct — Short alias

License

MIT License - see LICENSE for details.