cull: The Sleek TUI Tool That Reclaims Disk Space Fast

Running out of disk space? You're not alone. Every developer faces that dreaded moment when their system grinds to a halt, build processes fail, and Docker refuses to start. Traditional solutions like du -sh * or graphical disk utilities feel clunky, slow, and dangerously unsafe when deleting files. Enter cull—the interactive TUI disk space analyzer that transforms terminal-based file management from a chore into a seamless, visual experience. This powerful Go-powered tool scans directories in real-time, surfaces space-hungry files instantly, and lets you delete with confidence using its intuitive keyboard-driven interface. In this deep dive, you'll discover how cull works, master its advanced features, and learn why it's becoming the essential utility for developers who live in the terminal.

What Is cull? The Modern Developer's Disk Management Solution

cull is an interactive terminal user interface (TUI) disk space analyzer built by developer legostin and open-sourced under the MIT License. Unlike traditional command-line tools that dump static text output, cull creates a dynamic, living interface right in your terminal. It visualizes directory structures, calculates file sizes in the background, and lets you navigate, select, and delete files using intuitive keyboard shortcuts—all without ever leaving your command line.

The project addresses a critical pain point in modern development workflows: disk space management at scale. As projects grow, container images accumulate, and log files multiply, developers waste countless hours running du commands, waiting for results, and nervously executing rm -rf operations. cull eliminates this friction by providing immediate visual feedback and safe deletion patterns that move files to trash instead of permanently destroying them.

Written in Go, cull delivers cross-platform performance with minimal resource overhead. Its architecture leverages Go's concurrency model to size directories in parallel, ensuring the interface remains responsive even when scanning massive filesystems with millions of files. The tool has gained rapid traction in the developer community because it perfectly balances simplicity and power—beginners can start with cull . and immediately understand the interface, while power users leverage advanced filtering, sorting, and selection modes to perform complex cleanup operations in seconds.

The timing couldn't be better. As infrastructure-as-code and terminal-centric workflows dominate modern development, TUI applications are experiencing a renaissance. Tools like LazyGit, K9s, and now cull prove that rich interactive interfaces don't require bloated graphical applications. They deliver speed, efficiency, and keyboard-driven precision that GUI tools simply cannot match.

Key Features That Make cull Irresistible

Real-Time Background Directory Sizing

cull's most impressive technical achievement is its asynchronous size calculation engine. When you launch cull, it doesn't freeze while computing directory sizes. Instead, it displays entries immediately and spawns background goroutines that recursively calculate sizes. As results stream in, entries dynamically re-sort themselves, surfacing the largest space consumers within seconds.

This architecture uses Go's sync.WaitGroup and channel patterns to coordinate workers across directory trees. Each goroutine handles a subset of the filesystem, and a central aggregator updates the UI via a reactive loop. The result? You can start navigating and selecting files before the scan completes, turning wasted wait time into productive action.

Dual-Mode Deletion: Trash vs. Permanent

Safety dominates cull's design philosophy. By default, pressing d moves selected files to your system's trash/recycle bin, making recovery trivial. This uses native OS trash APIs on macOS and Linux, ensuring compatibility with desktop environments. For dangerous operations, tab switches to permanent deletion mode, clearly indicated by a red UI state change. Even then, cull requires explicit confirmation, preventing catastrophic mistakes.

This dual-mode system solves the #1 fear developers have with terminal file deletion: accidental data loss. You can experiment freely in trash mode, preview selections with e for dry-run verification, and only commit to permanent deletion when absolutely certain.

Deep Scan Largest Files Across Subdirectories

The Largest tab (shift+tab) performs a comprehensive flat scan across all subdirectories, surfacing the absolute biggest files regardless of location. This feature uses an optimized walk algorithm that bypasses traditional recursive depth-first search in favor of a breadth-first approach with early termination for ignored paths.

For developers dealing with monorepos, build artifacts, or log directories, this is a game-changer. Instead of manually drilling down through nested folders, you instantly see that 5GB Docker log file hiding in /var/lib/docker/containers/ or those ancient node_modules folders consuming gigabytes.

Intelligent Filtering and Search

Press f to activate live filtering that narrows entries as you type. The filter supports partial matching and updates the view in real-time, making it trivial to find all .log files, node_modules directories, or .tmp artifacts. The implementation uses a trie-like structure for efficient pattern matching, ensuring zero lag even with thousands of entries.

Combined with range selection (S), filtering enables surgical cleanup operations. Filter for *.cache, select all matches, and delete in three keystrokes. This pattern reduces multi-minute command-line operations to under five seconds.

Multi-Dimensional Sorting Options

cull offers four sort modes cycled via t: size (default), name, updated (mtime), and created (ctime). Each sort uses optimized comparison functions appropriate for its data type. Size sorting uses integer comparison with background updates, while name sorting employs locale-aware string comparison.

For CI/CD pipeline debugging, sorting by updated time surfaces recently modified files. For security audits, sorting by created time reveals unexpected file creation patterns. This flexibility transforms cull from a simple disk analyzer into a forensic investigation tool.

Platform-Specific Power Features

On macOS, space triggers Quick Look previews, letting you inspect files without opening external applications. The tool integrates with macOS's native trash system and respects .DS_Store and Finder metadata.

On Linux, cull respects XDG specifications for trash placement and follows symbolic links according to user-configured policies. The TUI renders correctly across GNOME Terminal, Konsole, iTerm2, and even headless SSH sessions.

Real-World Use Cases Where cull Dominates

1. Reclaiming Development Machine Disk Space

The Problem: Your MacBook's 512GB SSD is constantly full. Xcode caches occupy 40GB, Docker images consume 60GB, and old project node_modules folders hide another 30GB. Traditional cleanup requires running multiple commands and risky deletions.

The cull Solution: Launch cull ~ and immediately see a sorted list of your home directory's largest folders. shift+tab to Largest tab reveals individual files. Filter for node_modules, range-select all matches with S, and trash them in seconds. Switch to Browse mode, navigate to ~/Library/Developer/Xcode/DerivedData, and selectively delete old build caches. The entire operation completes in under two minutes with zero risk of permanent data loss.

The Outcome: Reclaim 80-100GB safely, improve system performance, and establish a weekly cleanup routine that takes 30 seconds.

2. Server Log File Management

The Problem: Production servers accumulate log files rapidly. A misconfigured application created 200GB of logs in /var/log/app/, causing the root filesystem to hit 95% capacity. SSH access is slow, and you need to act fast without accidentally deleting critical system logs.

The cull Solution: SSH into the server, install cull via go install, and run cull /var/log. The interface loads immediately while background sizing reveals the problematic app directory. Navigate into it, sort by size, and use range selection to target specific date ranges. e previews the deletion, confirming you're only removing application logs. Execute the deletion and watch disk usage drop from 95% to 40% in real-time.

The Outcome: Emergency resolved in minutes, system stability restored, and you can now schedule weekly cron jobs using cull --read-only for proactive monitoring.

3. Docker Build Context Optimization

The Problem: Your Docker build contexts are massive because they include unnecessary files. Building images takes forever, and you're exceeding registry size limits. You need to identify which files to .dockerignore but docker build output is cryptic.

The cull Solution: Run cull . in your project directory. The Largest tab immediately surfaces the 2GB data/ directory and 500MB of .git history that shouldn't be in builds. Filter for *.log, *.tmp, and cache/ directories to identify additional culprits. This visual audit reveals exactly what belongs in .dockerignore.

The Outcome: Reduce build context from 3GB to 150MB, cut build times by 80%, and establish a pre-commit hook that runs cull --read-only to catch future bloat.

4. CI/CD Artifact Cleanup

The Problem: Your Jenkins/GitLab CI server has a /builds directory containing artifacts from 500+ past pipeline runs. The disk is full, builds are failing, but you can't delete everything—you need to preserve the last 10 builds per project.

The cull Solution: Execute cull /builds and sort by updated time. Navigate to each project folder, use range selection to select builds older than 30 days, and preview deletions with e. The filter function helps isolate specific pipeline IDs. Trash obsolete artifacts while preserving recent builds.

The Outcome: Reclaim 300GB of disk space, restore CI pipeline reliability, and implement a monthly cleanup routine that takes 5 minutes instead of hours of scripting.

Step-by-Step Installation & Setup Guide

Prerequisites

cull requires Go 1.19+ for source installation. Pre-built packages via Homebrew and apt handle dependencies automatically. Your terminal must support 256 colors and Unicode for optimal rendering. Most modern terminals (iTerm2, GNOME Terminal, Windows Terminal) meet these requirements out-of-the-box.

Installation Method 1: macOS via Homebrew

The easiest installation uses the custom tap maintained by the developer:

# Add the custom tap to your Homebrew installation
brew tap legostin/tap

# Install cull
brew install cull

# Verify installation
cull --version

This method provides automatic updates when you run brew upgrade. The tap includes compiled binaries for both Intel and Apple Silicon Macs, ensuring native performance.

Installation Method 2: Linux via apt

For Debian-based distributions, use the custom apt repository:

# Add the repository to your sources list
echo "deb [trusted=yes] https://legostin.github.io/apt-repo/ /" | sudo tee /etc/apt/sources.list.d/cull.list

# Update package index
sudo apt update

# Install cull
sudo apt install cull

# Verify installation
cull --version

The [trusted=yes] flag is required since the repository isn't GPG-signed yet. For production servers, consider building from source instead.

Installation Method 3: Build from Source

Building from source guarantees you have the latest version and works on any platform with Go:

# Ensure Go 1.19+ is installed
go version

# Install directly from GitHub
go install github.com/legostin/cull@latest

# Verify the binary is in your PATH
cull --version

This method compiles cull specifically for your architecture and places the binary in $GOPATH/bin (usually ~/go/bin/). Add this to your PATH if it's not already there:

echo 'export PATH=$PATH:~/go/bin' >> ~/.bashrc
source ~/.bashrc

Post-Installation Configuration

cull respects the CULL_TRASH environment variable. Set it to 0 to disable trash functionality and force permanent deletion by default (not recommended):

# Add to your shell profile for persistent setting
echo 'export CULL_TRASH=1' >> ~/.bashrc  # Enable trash (default)

REAL Code Examples from the Repository

Example 1: Basic Directory Scanning

The simplest way to start cull is by scanning your current directory:

# Launch cull in the current directory
cull

This command initializes the TUI, starts background sizing of all subdirectories, and displays an interactive list. The interface appears immediately, with sizes populating dynamically. Use j/k or arrow keys to navigate, enter to descend into directories, and backspace to return to the parent.

Example 2: Scanning Specific Paths with Options

cull accepts path arguments and multiple flags for customized behavior:

# Scan your Downloads folder (common cleanup target)
cull ~/Downloads

# Run in read-only mode for safe auditing (no deletion allowed)
cull --read-only

# Skip confirmation prompts for faster bulk operations (use with caution!)
cull -y

# Limit Largest tab to show only top 5000 files (improves performance on huge filesystems)
cull -n 5000

The --read-only flag is perfect for production servers or when doing initial audits. The -y flag accelerates workflows but should only be used with trash mode enabled. The -n flag prevents memory issues on filesystems with millions of files.

Example 3: Safe Deletion Workflow

Here's a complete workflow for safely deleting files:

# Start cull in your target directory
cull /path/to/cleanup

# In the TUI:
# 1. Press 'f' and type '.log' to filter log files
# 2. Press 'S' (capital S) to range-select all filtered items
# 3. Press 'e' to preview what will be deleted
# 4. Press 'd' to move selected files to trash
# 5. If needed, press 'tab' first to switch to permanent mode (red indicator)

This workflow demonstrates cull's safety-first design. The e key is your best friend—it shows exact paths and sizes without executing anything. The visual feedback ensures you never delete the wrong files.

Example 4: Advanced Navigation and Sorting

Power users combine navigation and sorting for rapid cleanup:

# Start cull
cull ~/projects

# In the TUI:
# 1. Press 't' twice to sort by modification time
# 2. Press 'shift+tab' to view largest files across all projects
# 3. Press 'g' to jump to the top, 'G' to jump to the bottom
# 4. Press 'h' to toggle hidden files (reveals .git folders)
# 5. Press '?' anytime to view all keybindings

Sorting by updated time (t) helps identify stale projects. The Largest tab (shift+tab) is invaluable for finding space hogs across deeply nested monorepos. Mastering g and G accelerates navigation through long lists.

Advanced Usage & Best Practices

Create Shell Aliases for Common Tasks

Add these to your ~/.bashrc or ~/.zshrc:

# Quick cleanup alias for Downloads
alias cull-dl='cull ~/Downloads'

# Audit mode - read-only scan of root (requires sudo)
alias cull-audit='sudo cull --read-only /'

# Aggressive cleanup with auto-confirmation (use sparingly!)
alias cull-fast='cull -y ~/tmp'

# Docker cleanup helper
cull-docker() {
    cd /var/lib/docker && sudo cull --read-only
}

Integrate with Cron for Automated Monitoring

Schedule weekly disk usage reports:

# Add to crontab (crontab -e)
0 2 * * Sun cull --read-only /home >/tmp/disk-report.txt 2>&1

Best Practices for Safe Deletion

1. Always start with --read-only on unfamiliar systems
2. Use trash mode (tab to verify you're in trash state) for all bulk operations
3. Preview with e before any deletion over 1GB
4. Filter first, select second—narrow your scope before range selection
5. Sort by time when cleaning caches to avoid deleting actively used files
6. Check the UI indicator—trash mode shows a recycle icon; permanent mode shows a skull

Performance Optimization

For massive filesystems (>1 million files):

# Increase the item limit for Largest tab
cull -n 10000 /mnt/huge-filesystem

# Exclude network mounts by scanning specific local paths only
cull /var /home --read-only

Comparison with Alternatives

Why choose cull over ncdu? While ncdu is the veteran tool, its interface feels dated and lacks modern safety features. cull's trash integration and real-time updates provide a superior user experience. The Largest tab alone saves hours of manual navigation.

Why choose cull over dust/dua? These tools excel at generating reports but lack interactivity. cull lets you act on information immediately without switching contexts. The ability to preview deletions and recover from trash makes it production-safe.

Bottom line: cull combines the best of all worlds—ncdu's interactivity, dust's performance, and unique safety features no competitor offers.

Frequently Asked Questions

Is cull safe to use on production servers?

Absolutely—when used correctly. Always start with cull --read-only for auditing. The default trash mode ensures recoverability. For critical systems, run as a non-root user with appropriate permissions. The --read-only flag disables all deletion functions, making it 100% safe for diagnostics.

How is cull different from running du | sort?

du | sort provides static, one-dimensional output. cull offers real-time visual navigation, background sizing, interactive selection, and safe deletion. It's the difference between reading a map and having a GPS with live traffic updates. cull's TUI lets you explore relationships between directories and make informed decisions dynamically.

Can I recover files deleted with cull?

Yes—if you used trash mode (default). Files move to your system's trash/recycle bin. On macOS, check ~/.Trash. On Linux, check ~/.local/share/Trash/. Use your desktop trash UI or gio trash --empty to manage recovery. Permanent deletions cannot be recovered—that's why the UI clearly indicates the mode with color coding.

Does cull work on Windows?

Currently, cull supports macOS and Linux only. The developer focuses on Unix-like systems where terminal workflows dominate. Windows users can run cull via WSL2 (Windows Subsystem for Linux) with full functionality. Native Windows support may come in future releases.

How do I uninstall cull?

# macOS (Homebrew)
brew uninstall cull
brew untap legostin/tap

# Linux (apt)
sudo apt remove cull
sudo rm /etc/apt/sources.list.d/cull.list

# From source
rm ~/go/bin/cull

Can I customize the keybindings?

Currently, keybindings are fixed. The developer chose vim-style keys (j, k, g, G) to match developer muscle memory. Custom keybinding support is a highly requested feature on the GitHub issues page. For now, the ? help screen ensures you never forget the controls.

What about symbolic links and special files?

cull follows symbolic links by default, sizing their targets. This prevents confusion where a symlink appears size-zero but points to gigabytes of data. Device files, FIFOs, and sockets display with special indicators. Use h to toggle hidden files, which includes dotfiles and .git directories.

Conclusion: Why cull Belongs in Every Developer's Toolkit

cull represents the evolution of terminal-based system administration—combining the raw power of command-line tools with the intuitive interaction of modern TUIs. Its safety-first design, real-time performance, and thoughtful feature set solve real problems that plague developers daily. Whether you're cleaning up a laptop, managing servers, or optimizing Docker builds, cull turns hours of tedious work into minutes of focused, confident action.

The project's active development, MIT license, and growing community make it a reliable long-term investment. Unlike abandoned CLI tools, cull receives regular updates and responds to user feedback. Its Go-based architecture ensures it will remain fast, portable, and easy to install across platforms.

Ready to reclaim your disk space? Install cull today using brew install cull or go install github.com/legostin/cull@latest. Star the repository at https://github.com/legostin/cull to support the developer and get updates on new features. Your future self—staring at a full disk at 2 AM—will thank you.

Stop typing du -h | sort -h and start culling with confidence.