Tidyfiles
A versatile utility toolkit for recording, tracking, and managing file organization tasks from the command line. Each command logs timestamped entries to its own dedicated log file, with built-in statistics, multi-format export, search, and health-check capabilities.
Why Tidyfiles?
- Works entirely offline — your data stays on your machine
- Each command type maintains its own log file for clean data separation
- Built-in multi-format export (JSON, CSV, plain text)
- Full activity history with timestamped audit trail
- Search across all log files instantly
- Summary statistics with entry counts and disk usage
- Zero external dependencies — pure bash
Commands
Core Operations
| Command |
Description |
tidyfiles run <input> |
Record a run entry (no args: show recent entries) |
tidyfiles check <input> |
Record a check entry (no args: show recent entries) |
tidyfiles convert <input> |
Record a convert entry (no args: show recent entries) |
tidyfiles analyze <input> |
Record an analyze entry (no args: show recent entries) |
tidyfiles generate <input> |
Record a generate entry (no args: show recent entries) |
tidyfiles preview <input> |
Record a preview entry (no args: show recent entries) |
tidyfiles batch <input> |
Record a batch entry (no args: show recent entries) |
tidyfiles compare <input> |
Record a compare entry (no args: show recent entries) |
tidyfiles export <input> |
Record an export entry (no args: show recent entries) |
tidyfiles config <input> |
Record a config entry (no args: show recent entries) |
tidyfiles status <input> |
Record a status entry (no args: show recent entries) |
tidyfiles report <input> |
Record a report entry (no args: show recent entries) |
Utility Commands
| Command |
Description |
tidyfiles stats |
Show summary statistics (entry counts per type, total, disk usage) |
tidyfiles export <fmt> |
Export all data in json, csv, or txt format |
tidyfiles search <term> |
Search across all log files (case-insensitive) |
tidyfiles recent |
Show the 20 most recent activity log entries |
tidyfiles status |
Health check (version, entries, disk, last activity) |
tidyfiles help |
Display all available commands |
tidyfiles version |
Print version string |
Each core command works in two modes:
- With arguments: Saves a timestamped entry to
<command>.log and logs to history.log
- Without arguments: Displays the 20 most recent entries from that command's log
Data Storage
All data is stored locally in ~/.local/share/tidyfiles/. The directory contains:
run.log, check.log, convert.log, analyze.log, etc. — One log file per command type, storing YYYY-MM-DD HH:MM|input entrieshistory.log — Unified activity log with timestamped records of every command executedexport.json / export.csv / export.txt — Generated export files
Requirements
- Bash 4.0+ with
set -euo pipefail strict mode
- Standard Unix utilities:
grep, cat, tail, wc, du, date, sed
- No external dependencies or network access required
When to Use
- Tracking file organization tasks — Use
tidyfiles run "sorted ~/Downloads by file type" to log cleanup activities with timestamps
- Checking directory structure — Record structure checks with
tidyfiles check "~/projects: 45 dirs, 230 files, no empty dirs"
- Analyzing disk usage patterns — Log analysis results with
tidyfiles analyze "Documents folder: 12GB, 40% PDFs" and review with tidyfiles search "Documents"
- Batch file operations — Track batch processing with
tidyfiles batch "renamed 150 photos with date prefix" and review past batches
- Generating cleanup reports — Use
tidyfiles report "weekly cleanup: freed 3.2GB" then tidyfiles export csv for spreadsheet analysis
Examples
# Record file organization activities
tidyfiles run "organized Downloads into subfolders"
tidyfiles check "verified backup integrity: 100% match"
tidyfiles analyze "home directory: 85GB used, 15GB free"
# Track conversions and batch operations
tidyfiles convert "batch converted 200 PNGs to WebP"
tidyfiles batch "moved archived projects to cold storage"
tidyfiles generate "created folder structure for new project"
# Preview and compare
tidyfiles preview "dry-run sort of ~/Desktop: 45 files to move"
tidyfiles compare "before/after cleanup: 12GB freed"
# Search, review, and export
tidyfiles search "backup"
tidyfiles recent
tidyfiles stats
tidyfiles export json
tidyfiles export csv
# Configuration and reporting
tidyfiles config "default sort: by extension"
tidyfiles report "monthly cleanup summary: 25GB reclaimed"
tidyfiles status
Configuration
The data directory defaults to ~/.local/share/tidyfiles/. All log files are plain text with pipe-delimited fields (timestamp|value), making them easy to parse with standard Unix tools or import into spreadsheets.
Powered by BytesAgain | bytesagain.com | hello@bytesagain.com
1---2name: tidyfiles3description: Sort and organize files into folders by type, date, or rules. Use when decluttering dirs, checking structure, running cleanup, generating reports.4---5
6# Tidyfiles
7
8A versatile utility toolkit for recording, tracking, and managing file organization tasks from the command line. Each command logs timestamped entries to its own dedicated log file, with built-in statistics, multi-format export, search, and health-check capabilities.
9
10## Why Tidyfiles?
11
12- Works entirely offline — your data stays on your machine
13- Each command type maintains its own log file for clean data separation
14- Built-in multi-format export (JSON, CSV, plain text)
15- Full activity history with timestamped audit trail
16- Search across all log files instantly
17- Summary statistics with entry counts and disk usage
18- Zero external dependencies — pure bash
19
20## Commands
21
22### Core Operations
23
24| Command | Description |
25|---------|-------------|
26| `tidyfiles run <input>` | Record a run entry (no args: show recent entries) |
27| `tidyfiles check <input>` | Record a check entry (no args: show recent entries) |
28| `tidyfiles convert <input>` | Record a convert entry (no args: show recent entries) |
29| `tidyfiles analyze <input>` | Record an analyze entry (no args: show recent entries) |
30| `tidyfiles generate <input>` | Record a generate entry (no args: show recent entries) |
31| `tidyfiles preview <input>` | Record a preview entry (no args: show recent entries) |
32| `tidyfiles batch <input>` | Record a batch entry (no args: show recent entries) |
33| `tidyfiles compare <input>` | Record a compare entry (no args: show recent entries) |
34| `tidyfiles export <input>` | Record an export entry (no args: show recent entries) |
35| `tidyfiles config <input>` | Record a config entry (no args: show recent entries) |
36| `tidyfiles status <input>` | Record a status entry (no args: show recent entries) |
37| `tidyfiles report <input>` | Record a report entry (no args: show recent entries) |
38
39### Utility Commands
40
41| Command | Description |
42|---------|-------------|
43| `tidyfiles stats` | Show summary statistics (entry counts per type, total, disk usage) |
44| `tidyfiles export <fmt>` | Export all data in json, csv, or txt format |
45| `tidyfiles search <term>` | Search across all log files (case-insensitive) |
46| `tidyfiles recent` | Show the 20 most recent activity log entries |
47| `tidyfiles status` | Health check (version, entries, disk, last activity) |
48| `tidyfiles help` | Display all available commands |
49| `tidyfiles version` | Print version string |
50
51Each core command works in two modes:
52- **With arguments**: Saves a timestamped entry to `<command>.log` and logs to `history.log`
53- **Without arguments**: Displays the 20 most recent entries from that command's log
54
55## Data Storage
56
57All data is stored locally in `~/.local/share/tidyfiles/`. The directory contains:
58
59- **`run.log`**, **`check.log`**, **`convert.log`**, **`analyze.log`**, etc. — One log file per command type, storing `YYYY-MM-DD HH:MM|input` entries
60- **`history.log`** — Unified activity log with timestamped records of every command executed
61- **`export.json`** / **`export.csv`** / **`export.txt`** — Generated export files
62
63## Requirements
64
65- **Bash** 4.0+ with `set -euo pipefail` strict mode
66- Standard Unix utilities: `grep`, `cat`, `tail`, `wc`, `du`, `date`, `sed`
67- No external dependencies or network access required
68
69## When to Use
70
711. **Tracking file organization tasks** — Use `tidyfiles run "sorted ~/Downloads by file type"` to log cleanup activities with timestamps
722. **Checking directory structure** — Record structure checks with `tidyfiles check "~/projects: 45 dirs, 230 files, no empty dirs"`
733. **Analyzing disk usage patterns** — Log analysis results with `tidyfiles analyze "Documents folder: 12GB, 40% PDFs"` and review with `tidyfiles search "Documents"`
744. **Batch file operations** — Track batch processing with `tidyfiles batch "renamed 150 photos with date prefix"` and review past batches
755. **Generating cleanup reports** — Use `tidyfiles report "weekly cleanup: freed 3.2GB"` then `tidyfiles export csv` for spreadsheet analysis
76
77## Examples
78
79```bash
80# Record file organization activities
81tidyfiles run "organized Downloads into subfolders"
82tidyfiles check "verified backup integrity: 100% match"
83tidyfiles analyze "home directory: 85GB used, 15GB free"
84
85# Track conversions and batch operations
86tidyfiles convert "batch converted 200 PNGs to WebP"
87tidyfiles batch "moved archived projects to cold storage"
88tidyfiles generate "created folder structure for new project"
89
90# Preview and compare
91tidyfiles preview "dry-run sort of ~/Desktop: 45 files to move"
92tidyfiles compare "before/after cleanup: 12GB freed"
93
94# Search, review, and export
95tidyfiles search "backup"
96tidyfiles recent
97tidyfiles stats
98tidyfiles export json
99tidyfiles export csv
100
101# Configuration and reporting
102tidyfiles config "default sort: by extension"
103tidyfiles report "monthly cleanup summary: 25GB reclaimed"
104tidyfiles status
105```
106
107## Configuration
108
109The data directory defaults to `~/.local/share/tidyfiles/`. All log files are plain text with pipe-delimited fields (`timestamp|value`), making them easy to parse with standard Unix tools or import into spreadsheets.
110
111---
112Powered by BytesAgain | bytesagain.com | hello@bytesagain.com
bytesagain