Output Formats

JSON, CSV, text, and other output format options for CLEO commands

Output Formats

CLEO commands support multiple output formats for different use cases. This reference covers format options and usage patterns.

Format Auto-Detection

CLEO automatically detects the appropriate output format:

Context	Default Format
Interactive terminal (TTY)	Text (human-readable)
Piped output (non-TTY)	JSON
Explicit --format flag	Specified format

# Terminal: text output
cleo list

# Piped: JSON output
cleo list | jq '.tasks[]'

# Explicit format
cleo list --format json
cleo list --format text

Available Formats

JSON

Flag: --format json or --json

Use: LLM agents, scripting, data processing

cleo list --json

{
  "_meta": {
    "command": "list",
    "timestamp": "2025-01-19T12:00:00Z"
  },
  "summary": {
    "total": 15,
    "pending": 10,
    "active": 1
  },
  "tasks": [
    {
      "id": "T001",
      "title": "Implement auth",
      "status": "active"
    }
  ]
}

Text

Flag: --format text or --human

Use: Human reading, terminal display

cleo list --human

Tasks (15 total)
================

[T001] Implement auth (active) - high
       Phase: core | Labels: backend, security

[T002] Fix login bug (pending) - critical
       Phase: core | Labels: bug

Compact

Flag: --compact

Use: Quick overview, limited space

cleo list --compact

T001  active   high  Implement auth
T002  pending  crit  Fix login bug
T003  blocked  med   Add tests

CSV/TSV

Flag: --format csv or --format tsv

Use: Spreadsheets, data export

cleo export --format csv > tasks.csv

id,title,status,priority,labels
T001,Implement auth,active,high,"backend,security"
T002,Fix login bug,pending,critical,"bug"

Markdown

Flag: --format markdown

Use: Documentation, reports

cleo list --format markdown

## Tasks

- [ ] **T001**: Implement auth (high)
- [ ] **T002**: Fix login bug (critical)
- [x] **T003**: Set up CI (done)

JSON Envelope Structure

All JSON output follows a consistent envelope:

{
  "_meta": {
    "command": "command-name",
    "timestamp": "ISO-8601",
    "version": "0.54.0"
  },
  "summary": {
    // Command-specific summary
  },
  "data": {
    // Main payload (or "tasks", "task", etc.)
  },
  "error": {
    // Present only on error
    "code": "E_NOT_FOUND",
    "message": "Task T999 not found",
    "fix": "cleo list --status pending"
  }
}

Color Control

Disable Colors

# Standard NO_COLOR environment variable
NO_COLOR=1 cleo list

# Also works
CLEO_NO_COLOR=1 cleo list

Force Colors

# Force colors even in piped output
FORCE_COLOR=1 cleo list | less -R

Command-Specific Formats

list command

Format	Description
text	Full task details with colors
json	Complete task objects
compact	One-line per task
markdown	Checklist format
table	ASCII table

analyze command

Default: JSON (designed for LLM agents)

Format	Description
json	Structured analysis with scores
human	Text summary with recommendations

export command

Format	Description
csv	Comma-separated values
tsv	Tab-separated values
json	Full JSON export
jsonl	JSON Lines (one per line)

dash command

Format	Description
text	ASCII dashboard
json	Structured metrics
compact	Single-line summary

Progressive Disclosure Error Output

New in v0.74.2: Error responses use smart progressive disclosure - enough context for agent decision-making without verbose debugging data.

Error responses are optimized for LLM agent decision quality, not just token count. Large arrays are replaced with smart summaries containing decision-relevant fields.

Three-Level Progressive Disclosure

Level	Content	Size	Use Case
Smart Summary (default)	Decision-relevant fields only	~5K chars	Agent decision-making
Verbose	Full objects with all fields	~15K chars	Debugging

Default Behavior: Smart Summaries

Sessions include fields needed to choose the right session:

{
  "context": {
    "activeSessions": 9,
    "sessions": [
      {
        "id": "session_abc123",
        "name": "Auth-Epic-Work",      // ← Intent visible
        "scope": "epic:T001",           // ← Scope visible
        "focus": "T005"                 // ← Current task visible
      }
    ],
    "epics": [
      {
        "id": "T001",
        "title": "EPIC: Authentication System...",  // ← Truncated
        "status": "pending",
        "pending": 10                   // ← Workload visible
      }
    ],
    "_hint": "CLEO_VERBOSE=1 for full context"
  }
}

What Agents Can Do With Smart Summaries

• Find session by name: Match “Auth-Epic-Work” to their task
• Find session by scope: Resume epic:T001 session
• Compare epic workload: Pick epic with most pending tasks
• See current focus: Understand what’s in progress

Verbose Mode (Debugging)

CLEO_VERBOSE=1 cleo session start --name "debug"

Adds: stats, startMetrics, focusHistory, lastActivity, suspendedAt, full epic metadata.

Verbose mode is for debugging only. It includes 3x more data that agents don’t need for decision-making.

LLM Agent Best Practices

Use JSON for Parsing

Always use --json when processing output programmatically

Prefer Native Filters

Use --status, --label, --phase instead of | jq 'select(...)'

Check success Field

Always verify "success": true in JSON responses

Use find for Discovery

cleo find returns minimal output (99% less than list)

Next Steps

Exit Codes

CLI exit code reference

Configuration

Configure CLEO behavior