Skip to main content
All usage examples from the package, aggregated for quick reference.

​
engineError()

Create a typed engine error result with pino logging and correct exit code. View in API reference 
import { engineError } from './_error.js';

return engineError('E_NOT_FOUND', `Task ${id} not found`, {
  fix: `cleo show ${id}`,
  details: { taskId: id },
});

​
engineSuccess()

Create an engine success result. View in API reference 
import { engineSuccess } from './_error.js';

return engineSuccess({ tasks: filteredTasks, total: count });

​
taskShow()

Get a single task by ID. View in API reference 
const result = await taskShow('/project', 'T42');
if (result.success) console.log(result.data.task.title);

​
taskList()

List tasks with optional filters. View in API reference 
const result = await taskList('/project', { status: 'active', limit: 10 });

​
taskFind()

Fuzzy search tasks by title/description/ID. View in API reference 
const result = await taskFind('/project', 'authentication', 10);

​
taskExists()

Check if a task exists. View in API reference 
const result = await taskExists('/project', 'T42');
if (result.success && result.data.exists) { console.log('exists'); }

​
taskCreate()

Create a new task. View in API reference 
const result = await taskCreate('/project', {
  title: 'Implement auth',
  description: 'Add JWT-based authentication',
  priority: 'high',
});

​
taskUpdate()

Update a task’s fields. View in API reference 
const result = await taskUpdate('/project', 'T42', { status: 'active' });

​
taskComplete()

Complete a task (set status to done). View in API reference 
const result = await taskComplete('/project', 'T42', 'All tests passing');

​
taskDelete()

Delete a task. View in API reference 
const result = await taskDelete('/project', 'T42', true);

​
taskArchive()

Archive completed tasks. Moves done/cancelled tasks from active task data to archive. View in API reference 
const result = await taskArchive('/project', undefined, '2026-01-01');

​
taskNext()

Suggest next task to work on based on priority, phase alignment, age, and dependency readiness. View in API reference 
const result = await taskNext('/project', { count: 3, explain: true });

​
taskBlockers()

Show blocked tasks and analyze blocking chains. View in API reference 
const result = await taskBlockers('/project', { analyze: true });

​
taskTree()

Build hierarchy tree. View in API reference 
const result = await taskTree('/project', 'T1');

​
taskDeps()

Show dependencies for a task - both what it depends on and what depends on it. View in API reference 
const result = await taskDeps('/project', 'T42');

​
taskRelates()

Show task relations (existing relates entries). View in API reference 
const result = await taskRelates('/project', 'T42');

​
taskRelatesAdd()

Add a relation between two tasks. View in API reference 
const result = await taskRelatesAdd('/project', 'T42', 'T43', 'blocks', 'Needs auth first');

​
taskAnalyze()

Analyze a task for description quality, missing fields, and dependency health. View in API reference 
const result = await taskAnalyze('/project');

​
taskImpact()

Predict downstream impact of a free-text change description. Delegates to predictImpact from the intelligence module. Uses keyword matching against task titles/descriptions, then traces the reverse dependency graph for transitive effects. View in API reference 
const result = await taskImpact('/project', 'Refactor authentication module');

​
taskRestore()

Restore a cancelled task back to pending. View in API reference 
const result = await taskRestore('/project', 'T42', { cascade: true });

​
taskUnarchive()

Move an archived task back to active task data with status ‘done’ (or specified status). View in API reference 
const result = await taskUnarchive('/project', 'T42', { status: 'pending' });

​
taskReorder()

Change task position within its sibling group. View in API reference 
const result = await taskReorder('/project', 'T42', 0); // move to first

​
taskReparent()

Move task under a different parent. View in API reference 
const result = await taskReparent('/project', 'T42', 'T1');

​
taskPromote()

Promote a subtask to task or task to root (remove parent). View in API reference 
const result = await taskPromote('/project', 'T42');

​
taskReopen()

Reopen a completed task (set status back to pending). View in API reference 
const result = await taskReopen('/project', 'T42', { reason: 'Tests regressed' });

​
taskCancel()

Cancel a task (soft terminal state — reversible via restore). View in API reference 
const result = await taskCancel('/project', 'T42', 'No longer needed');

​
taskComplexityEstimate()

Deterministic complexity scoring from task metadata. View in API reference 
const result = await taskComplexityEstimate('/project', { taskId: 'T42' });

​
sessionStatus()

Get current session status. View in API reference 
const result = await sessionStatus('/project');
if (result.success && result.data.hasActiveSession) {
  console.log(result.data.session?.id);
}

​
sessionList()

List sessions with budget enforcement. When a limit is applied (explicit or default), the response includes _meta.truncated and _meta.total so agents know the result set was capped. View in API reference 
const result = await sessionList('/project', { active: true, limit: 5 });

​
sessionFind()

Lightweight session discovery — returns minimal session records. View in API reference 
const result = await sessionFind('/project', { status: 'active' });

​
sessionShow()

Show a specific session by ID. View in API reference 
const result = await sessionShow('/project', 'ses_20260401_abc123');

​
compose()

Composes an array of Middleware functions into a single Middleware function. Execution flows through the array from first to last, and returns bubble back up from last to first. View in API reference 
import { compose } from './pipeline.js';

const pipeline = compose([sanitizer, rateLimiter, protocolEnforcement]);
const response = await pipeline(request, handler);

​
mapCodebase()

Analyze a codebase and return structured mapping. When storeToBrain is true, findings are persisted to brain.db. View in API reference 
const result = await mapCodebase('/path/to/project', { focus: 'architecture' });

​
systemDash()

Project dashboard: task counts by status, active session info, current focus, recent completions. View in API reference 
const result = await systemDash('/project', { blockedTasksLimit: 5 });

​
parseIssueTemplates()

Parse all templates from the repo’s .github/ISSUE_TEMPLATE/ directory. View in API reference 
const result = parseIssueTemplates('/path/to/project');
if (result.success) {
  console.log(result.data.templates);
}

​
getTemplateForSubcommand()

Get template config for a specific subcommand (bug/feature/help). View in API reference 
const result = getTemplateForSubcommand('/path/to/project', 'bug');

​
generateTemplateConfig()

Generate and cache the config as .cleo/issue-templates.json. View in API reference 
const result = await generateTemplateConfig('/path/to/project');

​
validateLabels()

Validate that labels exist on a GitHub repo. View in API reference 
const result = validateLabels(['bug', 'enhancement'], repoLabels);

​
createRateLimiter()

Creates a rate limiting middleware for the dispatch pipeline. View in API reference 
import { createRateLimiter } from './rate-limiter.js';

const limiter = createRateLimiter({ query: { maxRequests: 50, windowMs: 30_000 } });

​
createSanitizer()

Creates a middleware that sanitizes incoming request parameters. Uses the canonical sanitization logic from security.ts to handle Task IDs, paths, string lengths, and enum validation. View in API reference 
import { createSanitizer } from './sanitizer.js';

const sanitizer = createSanitizer(() => process.cwd());

​
registerBackfillCommand()

Register the cleo backfill CLI command. View in API reference 
registerBackfillCommand(rootCommand);
// Adds: cleo backfill [--dry-run] [--rollback] [--embeddings]

​
registerBrainCommand()

Register the cleo brain command group. Registers a brain parent command and a maintenance subcommand that combines temporal decay, memory consolidation, and embedding backfill into one idempotent pass. View in API reference 
registerBrainCommand(rootCommand);
// Adds: cleo brain maintenance [--skip-decay] [--skip-consolidation] [--skip-embeddings] [--json]

​
registerExistsCommand()

Register the exists command. View in API reference 
registerExistsCommand(rootCommand);
// cleo exists T001 → exit 0 if found, exit 4 if not

​
registerReasonCommand()

Register the cleo reason command group and its subcommands. View in API reference 
registerReasonCommand(rootCommand);
// Adds: cleo reason why|similar|impact|timeline

​
createProtocolEnforcement()

Creates a middleware that enforces protocol compliance. Delegates to ProtocolEnforcer.enforceProtocol() which: - Passes through query operations untouched - Passes through mutate operations that don’t require validation - Validates protocol compliance on validated mutate operations after execution - In strict mode, blocks operations with protocol violations (exit codes 60-70) View in API reference 
import { createProtocolEnforcement } from './protocol-enforcement.js';

const enforcement = createProtocolEnforcement(true);

​
createVerificationGates()

Creates a middleware that enforces verification gates on task operations. View in API reference 
import { createVerificationGates } from './verification-gates.js';

const gates = createVerificationGates(true);

​
resolveTier()

Resolve tier from request params, defaulting to ‘standard’. View in API reference 
import { resolveTier } from './projections.js';

const tier = resolveTier(req.params, currentSession?.scope);