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

> Learn how vorssaint-utils --selftest and --sensors flags diagnose macOS system health and report hardware temperatures. Ensure your system is functioning optimally with these powerful tools.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-10

---

**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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) (lines 11-16) dispatches directly to these specialized routines:

```swift
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:

```bash
./build/Vorssaint --selftest

```

Example output showing a warning but successful completion:

```text
SELFTEST WARNING: memory usage unavailable
SELFTEST OK

```

Execute the sensor dump to inspect hardware monitoring capabilities:

```bash
./build/Vorssaint --sensors

```

Example truncated output:

```text
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) (lines 11-16), while the actual diagnostic implementations live in [`Sources/Vorssaint/Support/SelfTest.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.