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

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, 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.

# 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.

# 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 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, 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 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:

// 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, ensuring your custom implementation stays synchronized with upstream UI updates.

Automated Hardware Validation

The unit test suite in 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.

// 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 for easy support ticket generation.
• Test integration: Automated validation through 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, but the --selftest flag outputs raw text to stdout suitable for scripting and log collection, while the Feedback pane in 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, 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 and Sources/Vorssaint/Services/Feedback/FeedbackService.swift.

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