# StorageLens (CLI prototype)

StorageLens is a working prototype of a multi-target, read-only storage
audit tool: point it at several directories, shares, or drives at once
and it walks each one, computes total size, file count, and largest
files, then prints a single consolidated report ranked by size so an
IT admin can see at a glance which of their monitored locations is
closest to becoming a capacity problem. The report can be exported to
CSV for spreadsheets/ticketing, or emitted as full JSON for scripting.
It differs from the sibling DrivePulse tool, which is a single-target,
interactive space map meant for drilling into one folder at a time;
StorageLens is deliberately audit-only and admin-facing — it surveys
many targets side by side and ranks them, but takes no cleanup action
on any of them (DrivePulse and other cleanup-oriented sibling tools
handle acting on a target once StorageLens has told you where to
focus). Real SMART health data and true per-drive telemetry from the
full product concept require OS-specific hardware access (e.g.
WMI/S.M.A.R.T. queries on Windows, IOKit on macOS, sysfs/smartctl on
Linux) and are not implemented in this prototype; they are on the
roadmap. See ../plan.md for the full product plan.

## Build from source

Requires Go 1.24+, no external dependencies.

    go build -o storagelens .

Cross-compile for another platform:

    GOOS=windows GOARCH=amd64 go build -o storagelens.exe .
    GOOS=darwin  GOARCH=arm64 go build -o storagelens .

## Usage

    storagelens audit <target1> [<target2> ...] [--top-files N] [--csv report.csv] [--json]

For each <target> (an independent directory to scan), StorageLens walks
it recursively and computes: total size, total file count, and the
--top-files largest individual files within that target. It then prints
a summary table of all targets sorted by total size descending (biggest
storage consumer first), with each row showing the target path, total
size, file count, and — if a target doesn't exist or can't be read — a
clear error status for that row, without aborting the scan of the other
targets. After the table it prints a grand total across all successfully
scanned targets. For the top 3 targets by size specifically, it also
prints their --top-files largest individual files as a detail
breakdown, keeping the main table scannable while putting the heavy
detail only where it matters most.

Flags:

    --top-files N   Number of largest files to track per target
                    (default 5). Limits only the largest-files listing;
                    a target's own total size and file count always
                    reflect every file found, not just the top N.
    --csv <file>    Write a CSV report to <file>: one row per target
                    with path, total_bytes, human_readable_size,
                    file_count, and status (ok, or an error message for
                    unreadable/missing targets). Fields are properly
                    CSV-encoded (quoted when they contain commas, etc).
    --json          Print a full JSON report to stdout instead of the
                    human-readable table (the table and any CSV status
                    message move to stderr so stdout stays valid JSON).
                    The JSON includes every target's COMPLETE
                    largest-files list, not just the console's
                    top-3-targets-only detail view.
    -h, --help      Show help.

StorageLens is strictly read-only: it never deletes, moves, or modifies
anything on disk, in any mode.

## Prebuilt binaries

See ../downloads/ for prebuilt binaries (Windows/macOS/Linux) and
CHECKSUMS.txt for their SHA-256 hashes. These are unsigned indie builds —
Windows SmartScreen and macOS Gatekeeper will warn on first run, which is
expected until a code-signing certificate is in place.