📊 A minimal Rust-based CLI tool for measuring Apple Silicon GPU usage in snapshot form using IOReport.

siligpu queries the Apple Silicon GPU performance states and calculates the active usage percentage based on residency times. It's a low-level, fast, no-dependency snapshot tool for developers and power users.

• 🔍 One-shot snapshot of GPU residency (not a live monitor)
• 🍎 Designed for Apple Silicon Macs (M1, M2, M3, M4, M5...)
• ⏱️ Customizable sampling interval with -t, --time (supports ms, s, m, h)
• 📦 Uses low-level IOReport framework (no Metal dependency)
• 🦀 Written in Rust
• 🧩 Lightweight and fast
• 📄 JSON output support for easy parsing

Install via Homebrew (tap required):

# Add the tap
brew tap jarpex/formulaes https://github.com/jarpex/homebrew-formulae
# Install the CLI
brew install siligpu

git clone https://github.com/jarpex/siligpu.git
cd siligpu
cargo install --path .

siligpu [OPTIONS]

Time format examples: -t 500 (500ms), -t 2s (2 seconds), --time 1m (1 minute)

# Default (1 second interval, verbose)
siligpu
# 500 ms interval, summary mode
siligpu -t 500 -s
# 2-second interval, value-only
siligpu --time 2s -q
# JSON output
siligpu --json

GPU Stats / GPU Performance States
 OFF: 23840567 μs
 P1: 150146 μs
 P2: 50254 μs
 P3: 79121 μs
 ...
 → Total active: 346071 μs (active)
 → Total: 24186638 μs (total)
 → Usage: 1.43 %

{
 "usage_percentage": 1.43,
 "total_active_us": 346071,
 "total_time_us": 24186638,
 "states": [
 {
 "name": "OFF",
 "residency": 23840567,
 "is_active": false
 },
 {
 "name": "P1",
 "residency": 150146,
 "is_active": true
 }
 ]
}

• macOS (Big Sur 11.0 or later)
• Apple Silicon (M1, M2, M3, M4, M5...)

On unsupported hardware (e.g., Intel Macs or older macOS versions), siligpu will exit with an error explaining that GPU performance states are unavailable instead of crashing.

cargo test

Tests cover the duration parser, GPU channel math, and error handling for invalid input.