Bright utility · Apple Silicon · GPU · CPU · memory

bgpucap

BrightDate ecosystem command for Apple Silicon: run any command like time(1) and report GPU, CPU, and unified memory utilization. Crate name gpucap; CLI command bgpucap — like ripgrep/rg or btime.

# wrap a command — colored report on stderr $ bgpucap ffmpeg -i in.mp4 out.mp4 gpu avg 12.3% peak 45.6% cpu avg 8.1% peak 23.4% memory avg 52.0% peak 55.1% real 1.234567 s # machine output — CSV with BrightDate start/end $ bgpucap -f '%gA,%gP,%uA,%uP,%hA,%hP,%e,%Ws,%Wt' sleep 1 0.0,0.0,2.1,4.3,51.2,51.4,1.00,9628.198441000,9628.199441000
Install → Format spec crates.io GitHub
Usage

Wrap any command.

bgpucap forks and execs your command, polls metrics every 100 ms (configurable with --interval), then prints a summary to stderr. Exit status matches the child process. 

bgpucap sleep 1
bgpucap --color=bright -- ffmpeg -i in.mp4 out.mp4
bgpucap --interval 50 make -j8

GPU exerciser

gpuexercise is a subcommand (not a separate binary) that drives sustained GPU load via a Metal compute shader and feedback loop: 

bgpucap gpuexercise --percent 50 --seconds 10
bgpucap gpuexercise -f 'target=%tG gpu=%gA/%gP elapsed=%e' -p 75 -s 5

Requirements

macOS on Apple Silicon (M1/M2/M3/M4+), arm64 only. Reads AGX GPU metrics and unified memory statistics unavailable on Intel Macs or non-macOS platforms.

Color output

--color[=WHEN] — auto, always, never, plain, ansi, truecolor. --color-scheme — default or bright. Env: BGPUCAP_COLOR, BGPUCAP_COLOR_SCHEME (GPUCAP_* still accepted), plus NO_COLOR / CLICOLOR.

Format vs. color: When -f / --format (or BGPUCAP_FORMAT; GPUCAP_FORMAT still accepted) is set, output is always plain text — even with --color=always. This matches BrightDate ecosystem conventions: human reports colorize on TTY; machine format strings stay script-safe.

Machine output

-f / --format

Custom format strings follow BrightDate FORMAT-SPEC where applicable, plus gpucap-specific utilization specifiers. Set via -f or environment variable BGPUCAP_FORMAT (GPUCAP_FORMAT still accepted). 

bgpucap -f '%gA,%gP,%uA,%uP,%hA,%hP,%e,%Ws,%Wt' sleep 1
bgpucap -f 'cmd=%C x=%x gpu_peak=%gP start=%Ws' cargo build
gpucap

Utilization specifiers

All percentages output one decimal place, no % suffix.

Specifier Meaning
%gA / %gPGPU average / peak %
%uA / %uPCPU average / peak % (system-wide)
%hA / %hPUnified memory average / peak %
%tGExercise target GPU % (gpuexercise only)
BrightDate

Timing & timestamps

Shared with btime -f — see FORMAT-SPEC tiers A–C.

Specifier Meaning Output
%Ws / %NCommand start wall time{:.9} BrightDate days
%Wt / %nCommand end wall time{:.9} BrightDate days
%eElapsed secondssec.centis (GNU style)
%EElapsed wall timem:ss.cc or h:mm:ss
%BElapsed wall time{:.9} BrightDate days
%bElapsed millidays{:.6} (no suffix)
%dEElapsed millidays{:.6} md
%CCommand lineargv joined with spaces
%xExit statuschild exit code
%%Literal %
\t, \nTab / newline

Default machine format: %gA,%gP,%uA,%uP,%hA,%hP,%e,%Ws,%Wt\n

Data sources

What gets measured.

Metric Source Notes
GPU IOKit Device Utilization % IOReport fallback when IOKit unavailable
CPU Mach host_processor_info System-wide, not per-process
Memory host_statistics64 + hw.memsize Unified RAM on Apple Silicon

Samples are taken every --interval ms (default 100) while the child runs. Average and peak are computed over all samples.

Getting started

Install.

1

Cargo

cargo install gpucap
bgpucap sleep 1
2

Homebrew

brew tap digital-defiance/tap
brew install digital-defiance/tap/gpucap
bgpucap sleep 1
# Homebrew also symlinks gpucap → bgpucap
3

Verify

bgpucap --version
bgpucap --help
man bgpucap
bgpucap -f '%gA,%uA,%e' sleep 0.1
Reference

Man page

man/bgpucap.1 ships with the crate. Homebrew installs it as man bgpucap. The page documents options, format specifiers, environment variables, and the gpuexercise subcommand. 

man bgpucap          # after brew install
man bgpucap | grep -A2 FORMAT   # format specifiers

Crate name remains gpucap; command is bgpucap. Homebrew symlinks gpucap → bgpucap.