@cleocode/cleo

@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.