# Vorssaint-Utils Diagnostic Tools: A Complete Guide to CLI and UI Health Checks

> Explore the comprehensive diagnostic tools in vorssaint-utils. Learn about CLI health checks, SMC register dumps, graphical support data, and automated hardware sampling to ensure system health.

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

---

**Vorssaint-utils provides four built-in diagnostic tools: the `--selftest` command-line flag for system health checks, the `--sensors` flag for SMC register dumps, the graphical Feedback panel for formatted support data, and automated hardware samples for unit testing.**

The vorssaint-utils repository bundles lightweight, safe diagnostic utilities designed for developers, power-users, and support staff to quickly capture runtime environment states. These tools can be invoked via command-line flags, accessed through the SwiftUI interface, or integrated into automated test suites. Understanding these diagnostic capabilities helps troubleshoot installation issues and verify hardware compatibility across different Mac models.

## Command-Line Diagnostic Flags

The fastest way to access vorssaint-utils diagnostics is through command-line arguments when launching the binary. These flags execute immediately and output structured data to stdout without launching the full graphical interface.

### Self-Test Flag (--selftest)

Running `./vorssaint --selftest` executes a comprehensive internal health check that aggregates critical system information. According to the source code in [`Sources/Vorssaint/Support/FeedbackDiagnostics.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Support/FeedbackDiagnostics.swift), the `FeedbackDiagnostics.current()` method collects version metadata, build information, macOS version details, hardware model identifiers, active language settings, beta participation status, and configured update channels.

```bash

# Run a full self-test and print results to stdout

$ ./vorssaint --selftest
Vorssaint 3.3.3-beta.1 (2024-08-01)
macOS 13.5.2 (22G91)
MacBookPro18,3
Language: en-US
Beta: ✓
Update channel: Stable

```

This output format is intentionally designed for easy parsing by support scripts and manual inspection during troubleshooting sessions.

### SMC Sensors Dump (--sensors)

The `--sensors` flag emits a raw dump of System Management Controller (SMC) registers, providing low-level hardware telemetry essential for debugging temperature-related fan control issues or porting the utility to new Mac architectures.

```bash

# Dump raw SMC sensor data for hardware debugging

$ ./vorssaint --sensors
SMC Dump:
  - Fan0: 3200 RPM
  - GPU0Temp: 45°C
  - CPU0Temp: 48°C
  …

```

As noted in [`CHANGELOG.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/CHANGELOG.md) around version 3.3.3-beta.1, this diagnostic is particularly valuable when validating thermal management behaviors on unreleased hardware or troubleshooting sensor readout failures.

## Graphical Interface Diagnostics

For non-technical users or support scenarios requiring visual formatting, vorssaint-utils exposes the same diagnostic data through its SwiftUI interface.

### Feedback Diagnostics Pane

The **Feedback** window, implemented in [`Sources/Vorssaint/UI/Feedback/FeedbackView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Feedback/FeedbackView.swift), presents diagnostic information in a copy-paste friendly format ideal for support tickets. Users access this via the menu bar: **Send Feedback** → **Diagnostics** tab.

The view renders data collected by `FeedbackDiagnostics.current()` through the [`FeedbackService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeedbackService.swift) handler, which manages the presentation layer separately from the data collection logic. This separation ensures consistency between CLI output and GUI displays while allowing the service layer to optionally bundle log files with diagnostic reports when transmitting to remote feedback endpoints.

## Programmatic Access and Testing

Developers integrating vorssaint-utils or extending its functionality can access diagnostic capabilities directly through Swift code and the automated test suite.

### SwiftUI Integration

Embed diagnostic displays within custom views using the `FeedbackView` component with the `includeDiagnostics` parameter:

```swift
// Show diagnostics inside a custom SwiftUI view
import Vorssaint

struct DiagnosticsDemo: View {
    var body: some View {
        FeedbackView(includeDiagnostics: true)
    }
}

```

This imports the diagnostic rendering logic directly from [`Sources/Vorssaint/UI/Feedback/FeedbackView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Feedback/FeedbackView.swift), ensuring your custom implementation stays synchronized with upstream UI updates.

### Automated Hardware Validation

The unit test suite in [`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift) executes a **metrics test sample** that serves as an automated hardware diagnostic. This test validates the diagnostic collection pipeline by verifying that `FeedbackDiagnostics.current()` returns expected data structures and properly handles failure cases when hardware sensors are unavailable or return out-of-range values.

```swift
// Example test pattern from MetricsTests.swift
func testHardwareDiagnosticSample() {
    let diagnostics = FeedbackDiagnostics.current()
    XCTAssertNotNil(diagnostics.systemVersion)
    XCTAssertNotNil(diagnostics.hardwareModel)
    // Validates failure-case handling for unsupported sensors
}

```

## Summary

- **Self-test (`--selftest`)**: Provides comprehensive system health snapshots including version, hardware model, and configuration status via `FeedbackDiagnostics.current()`.
- **SMC sensors (`--sensors`)**: Dumps raw hardware telemetry for thermal and fan debugging, crucial for new Mac chip porting efforts.
- **Feedback pane**: Offers GUI-accessible, formatted diagnostics in [`FeedbackView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeedbackView.swift) for easy support ticket generation.
- **Test integration**: Automated validation through [`MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/MetricsTests.swift) ensures diagnostic reliability across hardware variations.

## Frequently Asked Questions

### How do I generate a diagnostic report for Vorssaint support?

Run `./vorssaint --selftest` from Terminal to generate a text-based health report containing version numbers, macOS build, hardware model, and configuration flags. Alternatively, open the **Send Feedback** window from the menu bar, navigate to the **Diagnostics** tab, and copy the formatted output directly into your support ticket.

### What is the difference between --selftest and the Feedback diagnostics pane?

Both tools execute the same underlying logic in [`FeedbackDiagnostics.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeedbackDiagnostics.swift), but the `--selftest` flag outputs raw text to stdout suitable for scripting and log collection, while the Feedback pane in [`FeedbackView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeedbackView.swift) presents styled, copy-friendly formatting designed for human readability and email support threads.

### Why would I use the --sensors diagnostic flag?

Use `--sensors` when porting vorssaint-utils to new Apple Silicon chips or debugging fan control algorithms. This flag reads raw SMC registers exposed by the System Management Controller, providing granular temperature and RPM data that helps verify thermal management behaviors on unsupported or prototype hardware.

### Where is the diagnostic data generated in the source code?

All diagnostic data originates from [`Sources/Vorssaint/Support/FeedbackDiagnostics.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Support/FeedbackDiagnostics.swift), specifically the `current()` method. This centralizes data collection for both CLI flags (`--selftest`, `--sensors`) and the graphical interface components defined in [`Sources/Vorssaint/UI/Feedback/FeedbackView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Feedback/FeedbackView.swift) and [`Sources/Vorssaint/Services/Feedback/FeedbackService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Feedback/FeedbackService.swift).