> ## Documentation Index
> Fetch the complete documentation index at: https://codluv.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# cleo — Examples

> Usage examples for the cleo package

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](/packages/cleo/api/functions#engineerror)

```typescript theme={null}
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](/packages/cleo/api/functions#enginesuccess)

```typescript theme={null}
import { engineSuccess } from './_error.js';

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

## `taskShow()`

*Get a single task by ID.*

[View in API reference](/packages/cleo/api/functions#taskshow)

```typescript theme={null}
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](/packages/cleo/api/functions#tasklist)

```typescript theme={null}
const result = await taskList('/project', { status: 'active', limit: 10 });
```

## `taskFind()`

*Fuzzy search tasks by title/description/ID.*

[View in API reference](/packages/cleo/api/functions#taskfind)

```typescript theme={null}
const result = await taskFind('/project', 'authentication', 10);
```

## `taskExists()`

*Check if a task exists.*

[View in API reference](/packages/cleo/api/functions#taskexists)

```typescript theme={null}
const result = await taskExists('/project', 'T42');
if (result.success && result.data.exists) { console.log('exists'); }
```

## `taskCreate()`

*Create a new task.*

[View in API reference](/packages/cleo/api/functions#taskcreate)

```typescript theme={null}
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](/packages/cleo/api/functions#taskupdate)

```typescript theme={null}
const result = await taskUpdate('/project', 'T42', { status: 'active' });
```

## `taskComplete()`

*Complete a task (set status to done).*

[View in API reference](/packages/cleo/api/functions#taskcomplete)

```typescript theme={null}
const result = await taskComplete('/project', 'T42', 'All tests passing');
```

## `taskDelete()`

*Delete a task.*

[View in API reference](/packages/cleo/api/functions#taskdelete)

```typescript theme={null}
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](/packages/cleo/api/functions#taskarchive)

```typescript theme={null}
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](/packages/cleo/api/functions#tasknext)

```typescript theme={null}
const result = await taskNext('/project', { count: 3, explain: true });
```

## `taskBlockers()`

*Show blocked tasks and analyze blocking chains.*

[View in API reference](/packages/cleo/api/functions#taskblockers)

```typescript theme={null}
const result = await taskBlockers('/project', { analyze: true });
```

## `taskTree()`

*Build hierarchy tree.*

[View in API reference](/packages/cleo/api/functions#tasktree)

```typescript theme={null}
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](/packages/cleo/api/functions#taskdeps)

```typescript theme={null}
const result = await taskDeps('/project', 'T42');
```

## `taskRelates()`

*Show task relations (existing relates entries).*

[View in API reference](/packages/cleo/api/functions#taskrelates)

```typescript theme={null}
const result = await taskRelates('/project', 'T42');
```

## `taskRelatesAdd()`

*Add a relation between two tasks.*

[View in API reference](/packages/cleo/api/functions#taskrelatesadd)

```typescript theme={null}
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](/packages/cleo/api/functions#taskanalyze)

```typescript theme={null}
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](/packages/cleo/api/functions#taskimpact)

```typescript theme={null}
const result = await taskImpact('/project', 'Refactor authentication module');
```

## `taskRestore()`

*Restore a cancelled task back to pending.*

[View in API reference](/packages/cleo/api/functions#taskrestore)

```typescript theme={null}
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](/packages/cleo/api/functions#taskunarchive)

```typescript theme={null}
const result = await taskUnarchive('/project', 'T42', { status: 'pending' });
```

## `taskReorder()`

*Change task position within its sibling group.*

[View in API reference](/packages/cleo/api/functions#taskreorder)

```typescript theme={null}
const result = await taskReorder('/project', 'T42', 0); // move to first
```

## `taskReparent()`

*Move task under a different parent.*

[View in API reference](/packages/cleo/api/functions#taskreparent)

```typescript theme={null}
const result = await taskReparent('/project', 'T42', 'T1');
```

## `taskPromote()`

*Promote a subtask to task or task to root (remove parent).*

[View in API reference](/packages/cleo/api/functions#taskpromote)

```typescript theme={null}
const result = await taskPromote('/project', 'T42');
```

## `taskReopen()`

*Reopen a completed task (set status back to pending).*

[View in API reference](/packages/cleo/api/functions#taskreopen)

```typescript theme={null}
const result = await taskReopen('/project', 'T42', { reason: 'Tests regressed' });
```

## `taskCancel()`

*Cancel a task (soft terminal state -- reversible via restore).*

[View in API reference](/packages/cleo/api/functions#taskcancel)

```typescript theme={null}
const result = await taskCancel('/project', 'T42', 'No longer needed');
```

## `taskComplexityEstimate()`

*Deterministic complexity scoring from task metadata.*

[View in API reference](/packages/cleo/api/functions#taskcomplexityestimate)

```typescript theme={null}
const result = await taskComplexityEstimate('/project', { taskId: 'T42' });
```

## `sessionStatus()`

*Get current session status.*

[View in API reference](/packages/cleo/api/functions#sessionstatus)

```typescript theme={null}
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](/packages/cleo/api/functions#sessionlist)

```typescript theme={null}
const result = await sessionList('/project', { active: true, limit: 5 });
```

## `sessionFind()`

*Lightweight session discovery -- returns minimal session records.*

[View in API reference](/packages/cleo/api/functions#sessionfind)

```typescript theme={null}
const result = await sessionFind('/project', { status: 'active' });
```

## `sessionShow()`

*Show a specific session by ID.*

[View in API reference](/packages/cleo/api/functions#sessionshow)

```typescript theme={null}
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](/packages/cleo/api/functions#compose)

```typescript theme={null}
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](/packages/cleo/api/functions#mapcodebase)

```typescript theme={null}
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](/packages/cleo/api/functions#systemdash)

```typescript theme={null}
const result = await systemDash('/project', { blockedTasksLimit: 5 });
```

## `parseIssueTemplates()`

*Parse all templates from the repo's .github/ISSUE\_TEMPLATE/ directory.*

[View in API reference](/packages/cleo/api/functions#parseissuetemplates)

```typescript theme={null}
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](/packages/cleo/api/functions#gettemplateforsubcommand)

```typescript theme={null}
const result = getTemplateForSubcommand('/path/to/project', 'bug');
```

## `generateTemplateConfig()`

*Generate and cache the config as .cleo/issue-templates.json.*

[View in API reference](/packages/cleo/api/functions#generatetemplateconfig)

```typescript theme={null}
const result = await generateTemplateConfig('/path/to/project');
```

## `validateLabels()`

*Validate that labels exist on a GitHub repo.*

[View in API reference](/packages/cleo/api/functions#validatelabels)

```typescript theme={null}
const result = validateLabels(['bug', 'enhancement'], repoLabels);
```

## `createRateLimiter()`

*Creates a rate limiting middleware for the dispatch pipeline.*

[View in API reference](/packages/cleo/api/functions#createratelimiter)

```typescript theme={null}
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](/packages/cleo/api/functions#createsanitizer)

```typescript theme={null}
import { createSanitizer } from './sanitizer.js';

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

## `registerBackfillCommand()`

*Register the `cleo backfill` CLI command.*

[View in API reference](/packages/cleo/api/functions#registerbackfillcommand)

```ts theme={null}
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](/packages/cleo/api/functions#registerbraincommand)

```ts theme={null}
registerBrainCommand(rootCommand);
// Adds: cleo brain maintenance [--skip-decay] [--skip-consolidation] [--skip-embeddings] [--json]
```

## `registerExistsCommand()`

*Register the exists command.*

[View in API reference](/packages/cleo/api/functions#registerexistscommand)

```ts theme={null}
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](/packages/cleo/api/functions#registerreasoncommand)

```ts theme={null}
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](/packages/cleo/api/functions#createprotocolenforcement)

```typescript theme={null}
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](/packages/cleo/api/functions#createverificationgates)

```typescript theme={null}
import { createVerificationGates } from './verification-gates.js';

const gates = createVerificationGates(true);
```

## `resolveTier()`

*Resolve tier from request params, defaulting to 'standard'.*

[View in API reference](/packages/cleo/api/functions#resolvetier)

```typescript theme={null}
import { resolveTier } from './projections.js';

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