Output Formats

In non-interactive mode (-N), towl supports five output formats. Terminal-based formats write to stdout; file-based formats require the -o flag with a matching file extension.

Note: Output format flags only apply in non-interactive mode. The interactive TUI has its own display. Use towl scan -N -f <format> to select a format.

Terminal / Table (default)

towl scan -N
# or explicitly:
towl scan -N -f table
towl scan -N -f terminal

Renders an ASCII table to stdout:

┌──────┬─────────────────────────┬──────────────────┬──────┬──────────┐
│ Type │ Description             │ File             │ Line │ Function │
├──────┼─────────────────────────┼──────────────────┼──────┼──────────┤
│ TODO │ Implement caching       │ src/lib/cache.rs │   42 │ process  │
│ FIXME│ Handle timeout          │ src/lib/net.rs   │  108 │ connect  │
└──────┴─────────────────────────┴──────────────────┴──────┴──────────┘

Note: table and terminal are aliases -- both produce the same output.

JSON

towl scan -N -f json -o todos.json

Produces structured JSON with a summary and TODOs grouped by type:

{
  "summary": {
    "total": 2,
    "by_type": {
      "TODO": 1,
      "FIXME": 1
    }
  },
  "todos": {
    "TODO": [
      {
        "id": "abc123",
        "file_path": "src/lib/cache.rs",
        "line_number": 42,
        "column_start": 5,
        "column_end": 30,
        "todo_type": "Todo",
        "description": "Implement caching",
        "original_text": "// TODO: Implement caching",
        "context_lines": ["fn process() {", "    // TODO: Implement caching", "    unimplemented!()"],
        "function_context": "process"
      }
    ]
  }
}

CSV

towl scan -N -f csv -o todos.csv

Produces a CSV file with a header row:

Type,Description,File,Line,Column Start,Column End,Function,Original Text,Context Lines
TODO,Implement caching,src/lib/cache.rs,42,5,30,process,// TODO: Implement caching,"fn process() {|    // TODO: Implement caching|    unimplemented!()"

Context lines are joined with | separators within a single quoted field.

Markdown

towl scan -N -f markdown -o todos.md

Produces a Markdown document with sections grouped by TODO type:

# TODOs

## TODO (1)

### Implement caching
- **File:** src/lib/cache.rs
- **Line:** 42
- **Function:** process

**Context:**
> fn process() {
>     // TODO: Implement caching
>     unimplemented!()

TOML

towl scan -N -f toml -o todos.toml

Produces a TOML file with a summary table and grouped items:

[summary]
total = 2

[summary.by_type]
TODO = 1
FIXME = 1

[[todos.TODO]]
description = "Implement caching"
file_path = "src/lib/cache.rs"
line_number = 42
function_context = "process"

Extension Validation

File-based formats require the output path to have a matching extension:

Mismatched extensions produce an error:

Error: Invalid output path: expected .json extension for JSON format

Choosing a Format