dysk-mac

v1.0.2

Published

8 months ago

A powerful command-line disk utility for macOS with emoji-enhanced output, SSD/HDD detection, and external drive support

💾 dysk-mac - macOS Disk Utility

The ultimate command-line disk utility for macOS - Get detailed disk information, monitor storage usage, and manage your drives with beautiful emoji-enhanced output.

dysk-mac is a powerful command-line disk utility for macOS that provides detailed information about mounted disks, including usage statistics, disk types (SSD vs HDD), external drive detection, and beautiful emoji-enhanced output.

🚀 Quick Start

# Install with Homebrew
brew tap nudelx/dysk-mac
brew install dysk-mac

# Run the tool
dysk-mac

✨ Features

📊 Comprehensive Disk Information: View detailed information about all mounted disks with emoji-enhanced output
🔍 Advanced Filtering: Filter disks based on usage percentage, free space, disk type, and more
📈 Flexible Sorting: Sort results by any disk property (size, usage, free space, etc.)
📋 Multiple Output Formats: Display as beautiful table, JSON, or CSV for data analysis
💾 Smart Detection: Automatically detects SSD vs HDD, external drives, and removable media
🎯 macOS Optimized: Uses native macOS diskutil and df commands for maximum compatibility
🚨 Usage Warnings: Visual indicators for high disk usage (⚠️ for >70%, 🚨 for >90%)
🔌 External Drive Support: Special handling for external SSDs and hard drives

Installation

Option 1: Homebrew (Recommended)

Install via Homebrew tap:

brew tap nudelx/dysk-mac
brew install dysk-mac

Option 2: Manual Installation

Clone or download this repository
Install dependencies:
```
npm install
```
Make the script executable:
```
chmod +x index.js
```
(Optional) Create a global link:
```
npm link
```

Usage

Basic Usage

Display all mounted disks in a formatted table:

./index.js
# or if globally linked:
dysk-mac

Command Line Options

| Option | Description | Example | | ---------- | ------------------------------ | -------------------------------------- | | --json | Output as JSON format | dysk-mac --json | | --csv | Output as CSV format | dysk-mac --csv | | --filter | Filter disks using expressions | dysk-mac --filter "usedPercent > 80" | | --sort | Sort by disk property | dysk-mac --sort free |

Examples

1. Basic Disk Information

dysk-mac

Output:

┌────────────────┬────────────────────────────┬───────────┬───────────┬────────┬───────────┬──────┬──────────┐
│ Disk           │ Mount                      │ Size (GB) │ Used (GB) │ Used % │ Free (GB) │ Type │ External │
├────────────────┼────────────────────────────┼───────────┼───────────┼────────┼───────────┼──────┼──────────┤
│ /dev/disk3s1s1 │ /                          │ 460.4     │ 10.5      │ 5%     │ 249.9     │ HDD  │ No       │
│ /dev/disk3s6   │ /System/Volumes/VM         │ 460.4     │ 0.0       │ 1%     │ 249.9     │ HDD  │ No       │
│ /dev/disk3s5   │ /System/Volumes/Data       │ 460.4     │ 192.3     │ 44%    │ 249.9     │ HDD  │ No       │
└────────────────┴────────────────────────────┴───────────┴───────────┴────────┴───────────┴──────┴──────────┘

2. Filter Disks by Usage

Show only disks with more than 70% usage:

dysk-mac --filter "usedPercent > 70"

3. Sort by Free Space

Display disks sorted by available free space (largest first):

dysk-mac --sort free

4. JSON Output

Get machine-readable JSON format:

dysk-mac --json

Output:

[
  {
    "filesystem": "/dev/disk1s1",
    "size": 500107862016,
    "used": 375080869888,
    "free": 125026992128,
    "usedPercent": 75,
    "mount": "/",
    "type": "SSD",
    "removable": false,
    "external": false
  }
]

5. CSV Output

Export data for spreadsheet analysis:

dysk-mac --csv

6. Combined Filtering and Sorting

Find external drives with low free space, sorted by usage:

dysk-mac --filter "external && free < 50e9" --sort usedPercent

Filter Expressions

The --filter option accepts JavaScript expressions that can reference any disk property:

| Property | Description | Example | | ------------- | --------------------------- | ---------------------------------- | | usedPercent | Percentage of disk used | usedPercent > 80 | | free | Free space in bytes | free < 10e9 (less than 10GB) | | size | Total disk size in bytes | size > 500e9 (larger than 500GB) | | external | Boolean for external drives | external (only external drives) | | type | Disk type ("SSD" or "HDD") | type === "SSD" | | removable | Boolean for removable media | removable |

Advanced Filter Examples

# Show only SSDs with high usage
dysk-mac --filter "type === 'SSD' && usedPercent > 90"

# Show external drives with less than 20GB free
dysk-mac --filter "external && free < 20e9"

# Show non-system drives (not mounted at /)
dysk-mac --filter "mount !== '/'"

# Show drives with more than 1TB total size
dysk-mac --filter "size > 1e12"

Output Fields

| Field | Description | | ------------- | ---------------------------------------- | | Disk | Device path (e.g., /dev/disk1s1) | | Mount | Mount point (e.g., /, /Volumes/Data) | | Size (GB) | Total disk size in gigabytes | | Used (GB) | Used space in gigabytes | | Used % | Percentage of disk space used | | Free (GB) | Available space in gigabytes | | Type | Disk type: SSD or HDD | | External | Whether the drive is external (Yes/No) |

Requirements

macOS (uses diskutil and df commands)
Node.js 14+ (for ES modules support)

Dependencies

cli-table3: For formatted table output
yargs: For command-line argument parsing

License

MIT License - feel free to use and modify as needed.

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Troubleshooting

Permission Issues

If you get permission errors, ensure the script is executable:

chmod +x index.js

No Output

If no disks are shown, check that you have mounted disks and the script has permission to run diskutil commands.

Filter Not Working

Make sure your filter expression is valid JavaScript. Common issues:

Use && for AND, || for OR
Use === for exact equality
Numbers should be in bytes (use e9 for GB, e12 for TB)

For Developers

Setting up Homebrew Tap

To make this tool available via Homebrew, see HOMEBREW_SETUP.md for detailed instructions.

Quick setup:

./setup-homebrew.sh

Building from Source

git clone https://github.com/nudelx/dysk-mac.git
cd dysk-mac
npm install
chmod +x index.js
./index.js

🔍 Keywords & Search Terms

dysk-mac is optimized for these search terms:

macOS disk utility
Command line disk tool
Disk usage monitor
SSD HDD detection
External drive utility
macOS storage management
Disk space analyzer
Homebrew disk tool
Terminal disk utility
macOS disk information

📈 Performance & Compatibility

Fast: Uses native macOS commands for optimal performance
Lightweight: Minimal dependencies, small footprint
Compatible: Works on macOS 10.15+ (Catalina and later)
Reliable: Built with Node.js 14+ ES modules
Secure: No external API calls, all local processing

🎯 Use Cases

System Administrators: Monitor disk usage across multiple systems
Developers: Check available space before builds or deployments
Power Users: Manage external drives and storage devices
DevOps: Integrate disk monitoring into automation scripts
Data Analysts: Export disk data for analysis and reporting

🌟 Why Choose dysk-mac?

Beautiful Output: Emoji-enhanced tables for better readability
Smart Detection: Automatically identifies SSD vs HDD and external drives
Flexible Filtering: Powerful JavaScript expressions for complex queries
Multiple Formats: Table, JSON, and CSV output options
Easy Installation: Simple Homebrew installation
Active Development: Regular updates and improvements

📞 Support & Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Contributions: Contributing Guide

Made with ❤️ for the macOS community