Understanding the --selftest and --sensors Flags in Vorssaint-Utils

The --selftest and --sensors flags in vorssaint-utils execute diagnostic routines that validate core macOS system capabilities and enumerate hardware temperature sensors, exiting with status code 0 on success or 1 on failure.

Vorssaint-Utils ships a single executable that operates as both a full-screen macOS application and a command-line diagnostic utility. When invoked with the vorssaint-utils --selftest or vorssaint-utils --sensors flags, the entry point in Sources/Vorssaint/main.swift bypasses the GUI to run specialized health checks, enabling automated verification in CI pipelines and detailed hardware analysis on Apple silicon devices.

What the --selftest Flag Validates

The --selftest flag triggers SelfTest.runAndExit(), implemented in Sources/Vorssaint/Support/SelfTest.swift (lines 7-36). This routine performs a comprehensive health check of the binary's ability to interact with essential macOS subsystems.

Specifically, the self-test validates:

• Power assertions and system uptime availability
• Memory usage tracking capabilities
• SMC temperature keys accessibility
• Network and disk counters readability
• User defaults (preferences) storage functionality
• Menu-bar icon assets integrity

The diagnostic prints SELFTEST OK when all checks pass or a detailed failure message if any subsystem is inaccessible. Per the implementation in Sources/Vorssaint/main.swift (lines 11-13), the process exits with code 0 on success or a non-zero status on error, allowing shell scripts and automated workflows to detect binary health immediately.

What the --sensors Flag Enumerates

The --sensors flag invokes SensorDump.runAndExit(), found in Sources/Vorssaint/Support/SelfTest.swift (lines 66-100). This routine enumerates every temperature sensor the application monitors and classifies each by component type.

When executed, the sensor dump:

1. Queries all available SMC temperature keys on the host machine
2. Classifies each sensor by category (cpu, gpu, battery, etc.)
3. Outputs a formatted table with component names, sensor keys, types, and current temperatures in Celsius

This output aids developers when porting sensor-mapping logic to new Apple silicon generations or debugging SMC readouts on unfamiliar hardware configurations.

Fail-Fast Implementation Details

Both diagnostic routines follow a fail-fast philosophy baked into the vorssaint-utils architecture. The argument parsing in Sources/Vorssaint/main.swift (lines 11-16) dispatches directly to these specialized routines:

if CommandLine.arguments.contains("--selftest") {
    SelfTest.runAndExit()
}
if CommandLine.arguments.contains("--sensors") {
    SensorDump.runAndExit()
}

Each routine terminates the process explicitly with exit(0) on success or exit(1) on error. This design ensures that calling scripts, GitHub Actions workflows, or manual terminal users receive unambiguous feedback through standard Unix exit codes without needing to parse log output.

Practical Usage Examples

Run the self-test from the terminal to verify binary health:

./build/Vorssaint --selftest

Example output showing a warning but successful completion:

SELFTEST WARNING: memory usage unavailable
SELFTEST OK

Execute the sensor dump to inspect hardware monitoring capabilities:

./build/Vorssaint --sensors

Example truncated output:

component    key   type   °C
cpu          Tp0f  type1  45.12
gpu          Tg0h  type2  38.67
battery      TB0T  type3  30.21

These commands are particularly valuable in release workflows where you must confirm that the compiled binary can access SMC keys before distribution.

Summary

• The --selftest flag executes a comprehensive health check via SelfTest.runAndExit() in Sources/Vorssaint/Support/SelfTest.swift, validating power assertions, memory tracking, SMC access, and UI assets.
• The --sensors flag runs SensorDump.runAndExit() to enumerate and classify all temperature sensors accessible to the application.
• Both routines are triggered from Sources/Vorssaint/main.swift and follow a fail-fast pattern, exiting with status 0 on success or 1 on failure.
• These flags enable CI/CD integration and hardware debugging without launching the full macOS GUI.

Frequently Asked Questions

What exit codes does vorssaint-utils return when using these flags?

According to the source code in Sources/Vorssaint/Support/SelfTest.swift, both --selftest and --sensors return exit code 0 on successful completion and exit code 1 when encountering errors. This follows standard Unix conventions, allowing shell scripts to use set -e or check $? to detect failures automatically.

Can I run these diagnostics on Apple silicon Macs?

Yes. The sensor dump routine specifically aids developers when porting to new Apple silicon generations by revealing available SMC temperature keys. The self-test validates cross-architecture capabilities including power assertions and memory monitoring that function on both Intel and Apple silicon Macs.

Where is the diagnostic logic implemented in the repository?

The command-line argument parsing resides in Sources/Vorssaint/main.swift (lines 11-16), while the actual diagnostic implementations live in Sources/Vorssaint/Support/SelfTest.swift. The self-test logic occupies lines 7-36, and the sensor enumeration logic occupies lines 66-100.

Why does the self-test warn about memory usage sometimes?

The self-test queries macOS system APIs to verify that the binary can track its own resource consumption. If the specific memory usage API is temporarily unavailable or restricted by system policy, the routine prints SELFTEST WARNING: memory usage unavailable but continues evaluating other subsystems, potentially still returning SELFTEST OK if remaining checks pass.

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