How to Use the --sensors Flag for SMC Temperature Keys in Vorssaint

Launch Vorssaint with --sensors to dump a complete list of SMC temperature keys with component classifications and current readings in Celsius.

The --sensors flag is a built-in diagnostic mode in Vorssaint that interrogates Apple's System Management Controller (SMC) for every temperature sensor available on your Mac. This feature is essential when porting Vorssaint to new hardware or automating temperature monitoring scripts.

What the --sensors Flag Does

When you invoke Vorssaint with --sensors, the application:

1. Creates an SMCClient instance to communicate with the Apple SMC controller.
2. Queries all SMC keys matching temperature prefixes: Tp*, Te*, Tg*, and TB[0-9]T.
3. Detects your CPU platform via TemperatureSensorSelector.currentPlatform() and checks for per-core temperature key availability through hasCPUCoreSet().
4. Filters readings to the valid range (1°C – 125°C) and outputs classified results.
5. Exits immediately after printing the table — no background monitoring starts.

The classification logic, defined in TemperatureSensorSelector.swift, maps keys to five component types:

• cpu — general processor temperature
• cpu-core — individual core readings (when available)
• cpu-aux — auxiliary CPU sensors
• gpu — graphics processor temperature
• battery — battery temperature sensors

Running the Command

Execute the binary from your build directory or installation path:

./build/Vorssaint --sensors

The output follows a fixed four-column format:

component    key   type   °C
cpu          Tp01  SInt16  45.23
cpu-core     Tp02  SInt16  46.11
gpu          Tg01  SInt16  48.37
battery      TB0T  SInt16  33.05

Columns are space-separated, and temperatures display with two decimal places.

Filtering and Scripting with --sensors Output

Because the output is plain text, you can pipe it to standard Unix tools for targeted extraction:

# Show only CPU core sensors

./build/Vorssaint --sensors | grep '^cpu-core'

# Extract just the temperature values for the GPU

./build/Vorssaint --sensors | awk '/^gpu/ {print $4}'

# Save to file for logging

./build/Vorssaint --sensors > smc_sensors_$(date +%Y%m%d).txt

For programmatic parsing, split on whitespace and read the fourth field as a floating-point number.

Source Code Implementation Details

The --sensors functionality spans three core files in the Vorssaint repository:

File	Purpose
Sources/Vorssaint/main.swift	Entry point that checks CommandLine.arguments for --sensors and calls SensorDump.runAndExit() (lines 14–16)
Sources/Vorssaint/Support/SelfTest.swift	Implements the SensorDump enum that performs the SMC enumeration, classification, and table formatting (lines 66–100)
Sources/Vorssaint/Services/Metrics/TemperatureSensorSelector.swift	Provides platform detection (currentPlatform()), core set detection (hasCPUCoreSet()), and key classification (isCPUCoreKey()), encoding Apple silicon generation mappings

The SensorDump enum uses TemperatureSensorSelector to determine whether your Mac exposes per-core temperature keys — critical because key naming conventions vary between Intel and Apple silicon generations.

When to Use --sensors

Porting to new hardware: Run --sensors on an unvalidated Mac model to discover which SMC keys exist and verify classification accuracy.

Scripting and automation: Identify the exact key names your specific machine uses before writing tools that read SMC temperatures directly.

Debugging sensor issues: Verify that Vorssaint sees the same keys you expect from other SMC utilities, confirming consistent SMC access.

Summary

• Invocation: ./Vorssaint --sensors dumps all classified temperature keys and exits.
• Output format: Space-separated columns for component, key, data type, and temperature in °C.
• Classification: Keys sorted into cpu, cpu-core, cpu-aux, gpu, and battery by TemperatureSensorSelector logic.
• Key implementation: main.swift triggers → SelfTest.swift (SensorDump) executes → TemperatureSensorSelector.swift classifies.
• Parsing friendly: Pipe to grep, awk, or other tools; temperatures are always floating-point with two decimals.

Frequently Asked Questions

What SMC temperature key prefixes does --sensors detect?

The SensorDump implementation queries keys matching Tp* (general/processor), Te* (external/environmental), Tg* (GPU), and TB[0-9]T (battery temperature). These prefixes cover the standard Apple SMC key namespace for thermal sensors across Intel and Apple silicon Macs.

Why does --sensors exit immediately instead of running normally?

The flag is designed as a diagnostic tool, not a monitoring mode. By exiting after the dump, it ensures clean integration into build scripts and CI pipelines without leaving a background process. For continuous monitoring, use Vorssaint's standard operation without --sensors.

How does Vorssaint classify keys when porting to a new Mac model?

The TemperatureSensorSelector.currentPlatform() method detects your specific CPU generation, then applies Apple-specific heuristics in isCPUCoreKey() to distinguish core versus auxiliary sensors. If your model returns unexpected classifications, the --sensors output helps identify which keys need updated mapping rules in TemperatureSensorSelector.swift.

Can I use --sensors output to read temperatures in my own program?

Yes. Parse the space-separated output directly, or use the discovery logic as reference: instantiate SMCClient, enumerate keys with the prefixes listed above, read SInt16 values, and convert using the SMC's fixed-point scaling (typically divide by 256 for °C). The SensorDump source in SelfTest.swift demonstrates the complete flow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}