### Install Pumas using Prebuilt Binary Source: https://context7.com/graelo/pumas/llms.txt Download a prebuilt binary, unzip it, and copy it to your system's PATH. Verify the installation with the version command. ```sh # Download from https://github.com/graelo/pumas/releases unzip pumas-aarch64-apple-darwin.zip sudo cp pumas /usr/local/bin/ pumas --version ``` -------------------------------- ### Install Pumas with Homebrew Source: https://github.com/graelo/pumas/blob/main/README.md Install Pumas using a Homebrew tap. Ensure you have Homebrew installed and configured. ```sh brew install graelo/tap/pumas ``` -------------------------------- ### Install Pumas from Prebuilt Binary Source: https://github.com/graelo/pumas/blob/main/README.md Install Pumas by downloading a prebuilt binary from the GitHub Releases page. This method involves unzipping the archive and copying the binary to your PATH. ```sh unzip pumas-aarch64-apple-darwin.zip ``` ```sh sudo cp pumas /usr/local/bin/ ``` -------------------------------- ### Install Pumas with x-cmd Source: https://github.com/graelo/pumas/blob/main/README.md Install Pumas using the x-cmd package manager. This is a convenient method if you are already using x-cmd. ```sh x install pumas ``` -------------------------------- ### Configure Pumas runtime settings Source: https://context7.com/graelo/pumas/llms.txt This example shows how to create a `RunConfig` struct to control Pumas' runtime behavior, including sample rate, history size, UI colors, and JSON output. It also demonstrates extracting UI colors for rendering. ```rust use pumas::config::{RunConfig, UiColors}; let config = RunConfig { sample_rate_ms: 1000, // 1 second polling history_size: 128, // keep 128 samples per metric accent_color: 2, // green labels gauge_fg_color: 2, // green gauge bars gauge_bg_color: 7, // white gauge background history_fg_color: 4, // blue sparklines history_bg_color: 7, // white sparkline background json: false, // run interactive TUI }; // Extract colors for the UI renderer let colors: UiColors = config.colors(); println!("accent ANSI: {}", colors.accent); // 2 ``` -------------------------------- ### Install Pumas with Cargo Source: https://github.com/graelo/pumas/blob/main/README.md Install Pumas directly from crates.io using Cargo. This requires a Rust development environment. ```sh cargo install pumas ``` -------------------------------- ### Run Pumas Command Source: https://github.com/graelo/pumas/blob/main/README.md Execute the Pumas tool to start monitoring. Sudo is required for `powermetrics` access. Use arrow keys to navigate tabs and Esc, q, x, or Ctrl-C to quit. ```sh sudo pumas run ``` -------------------------------- ### Verify Pumas Installation Source: https://github.com/graelo/pumas/blob/main/README.md Check the installed version of Pumas to confirm successful installation. This command should display the Pumas version number. ```sh pumas --version ``` -------------------------------- ### Define Pumas Alias Source: https://github.com/graelo/pumas/blob/main/README.md Provides an example of creating a shell alias to simplify running Pumas with sudo. ```sh alias pumas='sudo pumas run' ``` -------------------------------- ### Chip Identification and Power Ceilings Source: https://context7.com/graelo/pumas/llms.txt Illustrates the structure and example output of `SocInfo`, which identifies the SoC and retrieves power ceilings. This information is used for scaling TUI gauges and is exported in the JSON `soc` object. Supported chips range from M1 to M5 Ultra. ```rust // SocInfo is initialised once before the monitor loop. // Supported chips: M1 through M5 Ultra. // // Example output on Apple M2 Max: // { // cpu_brand_name: "Apple M2 Max", // num_cpu_cores: 12, // num_efficiency_cores: 4, // num_performance_cores: 8, // num_gpu_cores: 38, // max_cpu_w: 45.0, // max_gpu_w: 90.0, // max_ane_w: 10.0, // max_package_w: 145.0, // } // // Power ceilings for all known chips: // M1: cpu 20 W, gpu 20 W, ane 8 W // M1 Pro: cpu 22 W, gpu 18 W, ane 8 W // M1 Max: cpu 32 W, gpu 52 W, ane 8 W // M1 Ultra: cpu 70 W, gpu 130 W, ane 15 W // M2: cpu 22 W, gpu 22 W, ane 8 W // M2 Pro: cpu 38 W, gpu 52 W, ane 10 W // M2 Max: cpu 45 W, gpu 90 W, ane 10 W // M2 Ultra: cpu 75 W, gpu 200 W, ane 20 W // M3: cpu 14 W, gpu 14 W, ane 8 W // M3 Pro: cpu 16 W, gpu 16 W, ane 8 W // M3 Max: cpu 42 W, gpu 66 W, ane 10 W // M3 Ultra: cpu 65 W, gpu 120 W, ane 15 W // M4: cpu 18 W, gpu 17 W, ane 8 W // M4 Pro: cpu 35 W, gpu 35 W, ane 10 W // M4 Max: cpu 52 W, gpu 83 W, ane 10 W // M5: cpu 25 W, gpu 22 W, ane 8 W // M5 Pro: cpu 78 W, gpu 40 W, ane 10 W // M5 Max: cpu 78 W, gpu 75 W, ane 12 W // M5 Ultra: cpu 95 W, gpu 175 W, ane 18 W ``` -------------------------------- ### Calculate GPU Utilization Percentage Source: https://context7.com/graelo/pumas/llms.txt Extracts the GPU active ratio from the JSON stream, multiplies by 100, and rounds to get the utilization percentage. ```sh sudo pumas run --json | jq '.metrics.gpu.active_ratio * 100 | round' ``` -------------------------------- ### Pretty-print the First JSON Sample Source: https://context7.com/graelo/pumas/llms.txt Uses `head -1` to capture the first JSON output and `jq .` to pretty-print it, useful for inspecting the JSON structure. ```sh sudo pumas run --json | head -1 | jq . ``` -------------------------------- ### Stream CPU Active Ratio with JSON Mode Source: https://github.com/graelo/pumas/blob/main/README.md Demonstrates how to use Pumas in JSON mode to stream specific CPU metrics and process them with `jq`. Requires root privileges. ```sh $ sudo pumas run --json | jq '.metrics.e_clusters[0].cpus[2].active_ratio' 0.04624276980757713 0.11764705926179886 ^C ``` -------------------------------- ### Build Pumas from Source Source: https://github.com/graelo/pumas/blob/main/README.md Build Pumas from its source code. This involves cloning the repository, navigating into the directory, and compiling the release binary. ```sh git clone https://github.com/graelo/pumas.git ``` ```sh cd pumas ``` ```sh cargo build --release ``` -------------------------------- ### Pumas Run Command Help Source: https://github.com/graelo/pumas/blob/main/README.md Shows the help message for the 'pumas run' command, detailing available options for configuring the power usage monitor. ```sh $ pumas run --help Run the power usage monitor Usage: pumas run [OPTIONS] Options: -i, --sample-rate Update rate (milliseconds): min: 100 [default: 1000] --history-size History buffer size: default: 128 [default: 128] --accent-color Accent color for labels: ASCII code in 0~255, default: green [default: 2] --gauge-fg-color Gauge foreground color: ASCII code in 0~255, default: green [default: 2] --gauge-bg-color Gauge background color: ASCII code in 0~255, default: white [default: 7] --history-fg-color History foreground color: ASCII code in 0~255, default: blue [default: 4] --history-bg-color History background color: ASCII code in 0~255, default: white [default: 7] --json Print metrics to stdout as JSON instead of running the UI -h, --help Print help (see more with '--help') -V, --version Print version ``` -------------------------------- ### Display Pumas Run Command Help Source: https://context7.com/graelo/pumas/llms.txt Shows all available options for the `pumas run` command, including sample rate, history size, colors, and JSON output. ```sh sudo pumas run --help ``` -------------------------------- ### Pumas CLI Help Source: https://github.com/graelo/pumas/blob/main/README.md Displays the main help message for the Pumas command-line interface, listing available commands and global options. ```sh $ pumas --help A power usage monitor for Apple Silicon. Usage: pumas Commands: run Run the power usage monitor generate-completion Print a shell completion script to stdout help Print this message or the help of the given subcommand(s) Options: -h, --help Print help -V, --version Print version ``` -------------------------------- ### Configure Passwordless Sudo for Pumas Source: https://context7.com/graelo/pumas/llms.txt Set up a sudoers drop-in file to allow a specific user to run the 'pumas run' command without a password prompt. This is useful for automation scripts. ```sh # Create a drop-in file (do NOT edit /etc/sudoers directly) sudo visudo -f /etc/sudoers.d/pumas # Add this line, replacing "alice" with your username: # alice ALL=(ALL) NOPASSWD: /opt/homebrew/bin/pumas # Verify: run without password prompt sudo pumas run # Optional shell alias echo "alias pumas='sudo pumas run'" >> ~/.zshrc ``` -------------------------------- ### Extract Package Power Consumption Source: https://context7.com/graelo/pumas/llms.txt Uses `jq` to filter the JSON stream and extract the real-time package power consumption in watts. ```sh sudo pumas run --json | jq '.metrics.consumption.package_w' ``` -------------------------------- ### Run Pumas with JSON output Source: https://context7.com/graelo/pumas/llms.txt This code snippet demonstrates how to initialize and run the Pumas monitor with JSON output enabled. It sets a sample rate of 500ms and specifies JSON output, mimicking a command-line execution. ```rust use pumas:: Result, config::{RunConfig}, monitor, }; fn main() -> Result<()> { // Equivalent to `sudo pumas run --sample-rate 500 --json` let args = RunConfig { sample_rate_ms: 500, history_size: 128, accent_color: 2, gauge_fg_color: 2, gauge_bg_color: 7, history_fg_color: 4, history_bg_color: 7, json: true, }; monitor::run(args)?; Ok(()) } ``` -------------------------------- ### Configure Sudoers for Pumas Source: https://github.com/graelo/pumas/blob/main/README.md Shows how to configure sudoers to allow a user to run the Pumas command without a password. This involves creating a specific sudoers drop-in file. ```sudoers username ALL=(ALL) NOPASSWD: /opt/homebrew/bin/pumas ``` -------------------------------- ### Generate Bash Shell Completion Script Source: https://context7.com/graelo/pumas/llms.txt Generates a completion script for Bash and shows how to source it inline for immediate use. ```sh source <(pumas generate-completion bash) ``` -------------------------------- ### Run Pumas with Custom Sampling Rate and History Size Source: https://context7.com/graelo/pumas/llms.txt Configure Pumas to use a faster sampling rate (500ms) and a larger history buffer (256 samples) for more detailed monitoring. ```sh sudo pumas run --sample-rate 500 --history-size 256 ``` -------------------------------- ### Generate Fish Shell Completion Script Source: https://context7.com/graelo/pumas/llms.txt Generates a completion script for Fish shell and provides the command to save it to the appropriate configuration directory. ```sh pumas generate-completion fish > ~/.config/fish/completions/pumas.fish ``` -------------------------------- ### Parse and Display Hardware Metrics Source: https://context7.com/graelo/pumas/llms.txt Parses a `powermetrics` plist snapshot into a `Metrics` struct and prints aggregated hardware utilization, power consumption, and memory statistics. Requires the `pumas::metrics::Metrics` and `std::str::FromStr` imports. ```rust use pumas::metrics::Metrics; use std::str::FromStr; // Parse from a powermetrics plist snapshot (used in tests) let xml = std::fs::read_to_string("tests/data/powermetrics-output-m1.xml").unwrap(); let m = Metrics::from_str(&xml).unwrap(); // E-cluster summary println!("E-cluster freq: {:.1} MHz", m.e_clusters[0].freq_mhz); println!("E-cluster utilisation: {:.1} %", m.e_clusters[0].active_ratio() * 100.0); // Individual efficiency core let cpu0 = &m.e_clusters[0].cpus[0]; println!("CPU0 id: {}", cpu0.id); println!("CPU0 freq: {:.1} MHz", cpu0.freq_mhz); println!("CPU0 active ratio: {:.3}", cpu0.active_ratio); println!("CPU0 freq ratio: {:.3}", cpu0.freq_ratio()); // 0.0-1.0 // Power consumption println!("CPU power: {:.2} W", m.consumption.cpu_w); println!("GPU power: {:.2} W", m.consumption.gpu_w); println!("ANE power: {:.2} W", m.consumption.ane_w); println!("Pkg power: {:.2} W", m.consumption.package_w); // GPU println!("GPU freq: {:.1} MHz", m.gpu.freq_mhz); println!("GPU active: {:.3}", m.gpu.active_ratio); println!("GPU freq ratio: {:.3}", m.gpu.freq_ratio()); // Memory (after merge_sysinfo_metrics) println!("RAM used / total: {} / {} bytes", m.memory.ram_used, m.memory.ram_total); println!("RAM ratio: {:.1} %", m.memory.ram_usage_ratio() * 100.0); println!("Swap ratio: {:.1} %", m.memory.swap_usage_ratio() * 100.0); ``` -------------------------------- ### Stream JSON Metrics to a File Source: https://context7.com/graelo/pumas/llms.txt Redirects the JSON output from Pumas, with a 500ms sample rate, to a file named 'metrics.ndjson' for later analysis. ```sh sudo pumas run --json --sample-rate 500 > metrics.ndjson ``` -------------------------------- ### Generate Zsh Shell Completion Script Source: https://context7.com/graelo/pumas/llms.txt Generates a completion script for Zsh and instructs how to save it to your fpath for shell autocompletion. ```sh pumas generate-completion zsh > ~/.zfunctions/_pumas ``` -------------------------------- ### Collect and Display VM Statistics Source: https://context7.com/graelo/pumas/llms.txt Collects and displays page-level memory breakdowns using `VmStats::collect()`, matching macOS Activity Monitor's 'Memory Used' calculation. Requires the `pumas::modules::vm_stat::VmStats` import. ```rust use pumas::modules::vm_stat::VmStats; // (crate-internal; shown for reference) let stats = VmStats::collect().expect("vm_stat failed"); println!("Page size: {} bytes", stats.page_size); println!("Pages active: {}", stats.pages_active); println!("Pages wired: {}", stats.pages_wired); println!("Pages compressed: {}", stats.pages_compressed); println!("Pages free: {}", stats.pages_free); // Activity Monitor "Memory Used" = anonymous + wired + compressed let used = stats.activity_monitor_memory_used(); let total = stats.total_memory(); println!("Used: {:.1} GiB", used as f64 / 1_073_741_824.0); println!("Total: {:.1} GiB", total as f64 / 1_073_741_824.0); ``` -------------------------------- ### Stream Raw JSON Metrics Source: https://context7.com/graelo/pumas/llms.txt Runs Pumas in JSON streaming mode, outputting raw JSON objects to standard output for each sample interval. ```sh sudo pumas run --json ``` -------------------------------- ### Run Pumas with Custom Colors Source: https://context7.com/graelo/pumas/llms.txt Customize the TUI colors for accent, gauge foreground/background, and sparkline foreground/background using ANSI color codes. ```sh sudo pumas run --accent-color 6 --gauge-fg-color 5 --gauge-bg-color 0 \ --history-fg-color 3 --history-bg-color 0 ``` -------------------------------- ### Extract Efficiency Cluster CPU Active Ratio Source: https://context7.com/graelo/pumas/llms.txt Filters the JSON stream to show the active ratio for all CPUs within the first efficiency cluster. ```sh sudo pumas run --json | jq '.metrics.e_clusters[0].cpus[].active_ratio' ``` -------------------------------- ### Extract Specific Efficiency Cluster CPU Active Ratio Source: https://context7.com/graelo/pumas/llms.txt Extracts the active ratio for the third CPU core in the first efficiency cluster from the JSON stream. ```sh sudo pumas run --json | jq '.metrics.e_clusters[0].cpus[2].active_ratio' ``` -------------------------------- ### MetricKey Enum for Type-Safe History Keys Source: https://context7.com/graelo/pumas/llms.txt Use MetricKey enum variants to access system metrics like cluster activity, CPU utilization, frequency, GPU, ANE, power, and memory. This ensures compile-time safety over string-based keys. ```rust use pumas::metric_key::{ClusterId, MetricKey}; // Efficiency cluster 0 activity let key = MetricKey::ClusterActivePercent(ClusterId::efficiency(0)); // Performance cluster 1 activity (e.g. M1 Ultra P1) let key = MetricKey::ClusterActivePercent(ClusterId::performance(1)); // Super cluster 0 (M5 Pro/Max S-cluster) let key = MetricKey::ClusterActivePercent(ClusterId::super_core(0)); // Individual CPU core 3 utilisation let key = MetricKey::CpuActivePercent(3); // Individual CPU core 3 frequency ratio let key = MetricKey::CpuFreqPercent(3); // GPU, ANE let key = MetricKey::GpuActivePercent; let key = MetricKey::AneActivePercent; // Power let key = MetricKey::CpuPowerW; let key = MetricKey::GpuPowerW; let key = MetricKey::AnePowerW; let key = MetricKey::PackagePowerW; // Memory let key = MetricKey::RamUsageBytes; let key = MetricKey::SwapUsageBytes; ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.