towl 0.3.7

A fast CLI tool to scan codebases for TODO comments and output them in multiple formats
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# Quick Start

## 1. Initialise Configuration

Inside a git repository with a GitHub remote:

```bash
towl init
```

This creates `.towl.toml` with sensible defaults. GitHub owner/repo are auto-detected from `git remote get-url origin` at runtime (not stored in the config file).

If `.towl.toml` already exists, use `--force` to overwrite:

```bash
towl init --force
```

## 2. Scan for TODOs (Interactive)

```bash
# Scan the current directory (opens TUI)
towl scan

# Scan a specific path
towl scan src/

# Use a config file from a custom location
towl scan -c .config/.towl.toml
```

The interactive TUI lets you browse, filter, sort, peek at source code, and create GitHub issues from selected TODOs.

## 3. Scan for TODOs (Non-Interactive)

Use `--non-interactive` / `-N` for CI pipelines and scripting:

```bash
# Terminal table output
towl scan -N

# Enable verbose output (file counts, timing)
towl scan -N -v
```

## 4. Choose an Output Format

Non-interactive mode supports multiple output formats:

```bash
# Terminal table (default)
towl scan -N

# JSON file
towl scan -N -f json -o todos.json

# CSV file
towl scan -N -f csv -o todos.csv

# Markdown file
towl scan -N -f markdown -o todos.md

# TOML file
towl scan -N -f toml -o todos.toml
```

> **Note:** File-based formats (`json`, `csv`, `toml`, `markdown`) require the `-o` flag with a matching file extension. Terminal/table formats always output to stdout.

## 5. Filter by Type

```bash
# Only TODO comments
towl scan -N -t todo

# Only FIXME comments
towl scan -N -t fixme

# Only BUG comments
towl scan -N -t bug
```

Available types: `todo`, `fixme`, `hack`, `note`, `bug`

## 6. Create GitHub Issues

Set your GitHub token:

```bash
export TOWL_GITHUB_TOKEN=ghp_your_token_here
```

Then create issues from TODOs:

```bash
# Create GitHub issues (non-interactive)
towl scan -N -g

# Preview issues without creating them
towl scan -N -g -n
```

In interactive mode, select TODOs with `Space` and press `Enter` to create issues.

## 7. View Configuration

```bash
towl config

# From a custom config path
towl config -c .config/.towl.toml
```

Displays a tree view of all active settings including file extensions, exclude patterns, comment prefixes, TODO patterns, and GitHub configuration.

You can also set the `TOWL_CONFIG` environment variable to avoid passing `--config` every time:

```bash
export TOWL_CONFIG=.config/.towl.toml
towl scan
```