Skip to main content

​
Overview

The Output schema defines the standard JSON envelope for all successful CLEO command responses. It provides a consistent structure for returning data from commands, including metadata, task objects, task arrays, change tracking, and warnings.

​
Schema Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "schemaVersion": "1.0.0",
  "$id": "https://cleo-dev.com/schemas/v1/output.schema.json",
  "title": "Claude-TODO Response Envelope",
  "description": "Standard JSON envelope for all successful cleo command responses",
  "type": "object",
  "required": ["_meta", "success"],
  "additionalProperties": true
}

​
Properties

​
Root Properties

PropertyTypeRequiredDescription
$schemastringNoSchema URL for validation (must be https://cleo-dev.com/schemas/v1/output.schema.json)
_metaobjectYesResponse metadata
successbooleanYesAlways true for successful responses
summaryobjectNoAggregated statistics or summary data
dataanyNoGeneric data payload (type depends on command)
taskobjectNoSingle task object (for add, update, show commands)
tasksarrayNoArray of task objects (for list commands)
taskIdstringNoTask ID affected by operation
changesobjectNoChange tracking for update operations
warningsarrayNoNon-fatal warnings

​
_meta Object

PropertyTypeRequiredDescription
formatstringNoOutput format identifier (always “json”)
versionstringYesCLEO version (semver format)
commandstringYesCommand name that generated this response
timestampstringYesISO-8601 UTC timestamp of response generation
checksumstringNoSHA256 checksum of source file (64 hex chars)
execution_msintegerNoExecution time in milliseconds

​
Task Object

PropertyTypeRequiredDescription
idstringNoTask identifier (T001+, expandable)
typestringNoHierarchy type: epic, task, or subtask
parentIdstring/nullNoParent task ID or null for root tasks
sizestring/nullNoTask size estimate: small, medium, large, or null
titlestringNoTask title (minLength: 1)
descriptionstringNoTask description
statusstringNoTask status: pending, active, blocked, or done
prioritystringNoTask priority: critical, high, medium, or low
createdAtstringNoISO 8601 timestamp when task was created
completedAtstring/nullNoISO 8601 timestamp when task was completed

​
Changes Object

The changes object tracks modifications made during update operations. Each property represents a changed field with before and after values: 
{
  "changes": {
    "status": {
      "before": "pending",
      "after": "active"
    },
    "priority": {
      "before": "medium",
      "after": "high"
    }
  }
}

​
Warnings Array Items

PropertyTypeRequiredDescription
codestringYesWarning code with W_ prefix (e.g., W_DEPRECATED)
messagestringYesHuman-readable warning message
suggestionstring/nullNoSuggested action to address the warning

​
Examples

​
Task Creation Response

{
  "$schema": "https://cleo-dev.com/schemas/v1/output.schema.json",
  "_meta": {
    "format": "json",
    "version": "1.0.0",
    "command": "cleo add",
    "timestamp": "2026-01-27T22:30:00Z",
    "execution_ms": 45
  },
  "success": true,
  "task": {
    "id": "T2598",
    "type": "task",
    "parentId": "T2591",
    "size": "medium",
    "title": "Document remaining schemas",
    "description": "Create documentation for config and log schemas",
    "status": "pending",
    "priority": "high",
    "createdAt": "2026-01-27T22:30:00Z",
    "completedAt": null
  },
  "taskId": "T2598"
}

​
Task List Response

{
  "$schema": "https://cleo-dev.com/schemas/v1/output.schema.json",
  "_meta": {
    "format": "json",
    "version": "1.0.0",
    "command": "cleo list",
    "timestamp": "2026-01-27T22:35:00Z",
    "execution_ms": 23
  },
  "success": true,
  "summary": {
    "total": 5,
    "byStatus": {
      "pending": 2,
      "active": 2,
      "blocked": 1,
      "done": 0
    }
  },
  "tasks": [
    {
      "id": "T2597",
      "type": "task",
      "parentId": "T2591",
      "title": "Document high-priority schemas",
      "status": "active",
      "priority": "high"
    },
    {
      "id": "T2598",
      "type": "task",
      "parentId": "T2591",
      "title": "Document remaining schemas",
      "status": "pending",
      "priority": "high"
    }
  ]
}

​
Task Update Response with Changes

{
  "$schema": "https://cleo-dev.com/schemas/v1/output.schema.json",
  "_meta": {
    "format": "json",
    "version": "1.0.0",
    "command": "cleo update",
    "timestamp": "2026-01-27T22:40:00Z",
    "execution_ms": 38
  },
  "success": true,
  "task": {
    "id": "T2597",
    "type": "task",
    "parentId": "T2591",
    "title": "Document high-priority schemas",
    "status": "done",
    "priority": "high",
    "createdAt": "2026-01-27T22:12:58Z",
    "completedAt": "2026-01-27T22:40:00Z"
  },
  "taskId": "T2597",
  "changes": {
    "status": {
      "before": "active",
      "after": "done"
    },
    "completedAt": {
      "before": null,
      "after": "2026-01-27T22:40:00Z"
    }
  }
}

​
Response with Warnings

{
  "$schema": "https://cleo-dev.com/schemas/v1/output.schema.json",
  "_meta": {
    "format": "json",
    "version": "1.0.0",
    "command": "cleo complete",
    "timestamp": "2026-01-27T22:45:00Z",
    "execution_ms": 52
  },
  "success": true,
  "task": {
    "id": "T2597",
    "type": "task",
    "title": "Document high-priority schemas",
    "status": "done"
  },
  "warnings": [
    {
      "code": "W_CHILDREN_ACTIVE",
      "message": "Task has active child tasks that may need attention",
      "suggestion": "Review child tasks T2598, T2599 before completing parent"
    }
  ]
}

​
Validation Response

{
  "$schema": "https://cleo-dev.com/schemas/v1/output.schema.json",
  "_meta": {
    "format": "json",
    "version": "1.0.0",
    "command": "cleo validate",
    "timestamp": "2026-01-27T22:50:00Z",
    "execution_ms": 125,
    "checksum": "a1b2c3d4e5f6..."
  },
  "success": true,
  "summary": {
    "filesChecked": 3,
    "valid": 3,
    "invalid": 0,
    "errors": []
  },
  "data": {
    "todo.json": { "valid": true },
    "sessions.json": { "valid": true },
    "config.json": { "valid": true }
  }
}

​
Usage

The output schema is used throughout CLEO:
  • CLI Success Output: All successful cleo commands output in this format when using --format json
  • API Responses: Success responses from any CLEO API endpoints
  • Script Integration: Bash scripts can parse structured responses
  • Agent Communication: LLM agents receive consistent response structures

​
Response Patterns

Different commands populate different fields:
Command TypePopulated Fields
cleo add, cleo showtask, taskId
cleo listtasks, summary
cleo updatetask, taskId, changes
cleo completetask, taskId, warnings
cleo validatesummary, data
cleo configdata

​
Warning Codes

Common warning codes include:
Warning CodeDescription
W_DEPRECATEDFeature or option is deprecated
W_CHILDREN_ACTIVEParent task has active children
W_SCOPE_OVERLAPSession scope overlaps with another session
W_LARGE_TASKTask size is large, consider breaking down
W_STALE_DATAData hasn’t been updated recently

​
Additional Properties

The schema allows additionalProperties: true at the root level, enabling commands to include command-specific fields as needed while maintaining the core structure.