# How to Configure Vorssaint-Utils: Complete UserDefaults and Settings Guide

> Configure Vorssaint-Utils effortlessly using UserDefaults and settings. Learn GUI-based and programmatic options for instant persistence. Explore the complete guide now.

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

---

**Vorssaint-utils stores every user-adjustable option in macOS `UserDefaults` using keys defined in [`Sources/Vorssaint/Core/Defaults.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Defaults.swift), enabling both GUI-based and programmatic configuration that persists instantly across app launches.**

The vorssaint-utils repository provides a macOS utility suite where all customization flows through a centralized defaults system. Whether you adjust settings through the SwiftUI preferences interface or modify values directly via code, every change writes to the standard macOS preferences domain `com.vorssaint.utils`. This architecture ensures immediate persistence without requiring manual file editing or restart sequences.

## Where Vorssaint-Utils Stores Configuration

All configuration values live in **`UserDefaults.standard`** under the bundle identifier `com.vorssaint.utils`. The central enumeration of valid keys resides in **[`Sources/Vorssaint/Core/Defaults.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Defaults.swift)**, which serves as the single source of truth for both the application services and the Settings UI.

When vorssaint-utils launches, it reads initial values from the macOS preferences plist. The SwiftUI views under **`Sources/Vorssaint/UI/Settings/`** bind directly to these `UserDefaults` keys, creating a reactive two-way sync: user interactions update storage immediately, and programmatic changes reflect instantly in the interface.

## Configuration Categories and UI Locations

Vorssaint-utils organizes settings into logical groups, each managed by specific SwiftUI views and underlying service layers.

### Panels and Layout Visibility

The panel system controls which utility panels appear in the interface. Settings for panel visibility are managed in **[`Sources/Vorssaint/UI/Settings/PanelLayout.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/PanelLayout.swift)**, with boolean flags like `DefaultsKey.panelUtilitiesEnabled` determining whether specific panels render.

### Global Shortcuts

Window management shortcuts are configured in **[`Sources/Vorssaint/UI/Settings/ShortcutsSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/ShortcutsSettings.swift)**. This view manages keys including:
- `DefaultsKey.windowLayoutShortcutsEnabled` – Toggles directional window snapping
- `DefaultsKey.windowGestureEnabled` – Enables gesture-based window control
- `DefaultsKey.windowDirectionalShortcut` – Stores the specific key combination string (e.g., "⌥⌘←")

The **`WindowLayoutService`** (found in **[`Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift)**) polls these defaults before executing shortcut actions.

### App and Volume Exclusions

Exclusion lists prevent specific apps or volumes from triggering certain features. **[`Sources/Vorssaint/UI/Settings/WindowPreviewExclusionsList.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/WindowPreviewExclusionsList.swift)** manages `DefaultsKey.windowPreviewExcludedApps` as a string array, while disk exclusions reside in sibling files using `DefaultsKey.diskEjectExcludedVolumes`.

### Radial Menu Profiles

The radial launcher configuration stores complex data structures in **[`Sources/Vorssaint/UI/Settings/RadialMenuSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/RadialMenuSettings.swift)**. Unlike simple booleans, radial menu profiles use `DefaultsKey.radialMenuProfiles` with `Data` serialization to persist dictionary or array structures.

### Keep-Awake Automation

The keep-awake feature, controlled via **[`Sources/Vorssaint/UI/Settings/KeepAwakeAutomationView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/KeepAwakeAutomationView.swift)**, stores bundle identifiers in `DefaultsKey.keepAwakeRunningAppBundleIDs`. This string array defines which running applications prevent display sleep.

### Update Behavior

Automatic update settings live in **[`Sources/Vorssaint/Services/Update/UpdateService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Update/UpdateService.swift)**, checking `DefaultsKey.autoCheckUpdates` on launch and respecting media override flags stored in `DefaultsKey.updateShowcaseMediaOverride`.

## Programmatic Configuration

You can modify vorssaint-utils settings directly from Swift scripts or external modules without launching the GUI. All changes use the same `DefaultsKey` constants defined in the core module.

Enable window gestures via code:

```swift
import Foundation

// Enable window-gesture shortcuts
UserDefaults.standard.set(true, forKey: DefaultsKey.windowGestureEnabled)

```

Add an application to the window preview exclusion list:

```swift
var excluded = UserDefaults.standard.stringArray(forKey: DefaultsKey.windowPreviewExcludedApps) ?? []
excluded.append("com.example.SomeApp")
UserDefaults.standard.set(excluded, forKey: DefaultsKey.windowPreviewExcludedApps)

```

Configure keep-awake for Safari:

```swift
let bundleID = "com.apple.Safari"
var ids = UserDefaults.standard.stringArray(forKey: DefaultsKey.keepAwakeRunningAppBundleIDs) ?? []
if !ids.contains(bundleID) { ids.append(bundleID) }
UserDefaults.standard.set(ids, forKey: DefaultsKey.keepAwakeRunningAppBundleIDs)

```

Disable the radial menu entirely:

```swift
UserDefaults.standard.set(false, forKey: DefaultsKey.radialMenuEnabled)

```

Reset specific shortcuts to factory defaults by removing the keys:

```swift
UserDefaults.standard.removeObject(forKey: DefaultsKey.windowLayoutShortcutsEnabled)
UserDefaults.standard.removeObject(forKey: DefaultsKey.windowGestureEnabled)
UserDefaults.standard.removeObject(forKey: DefaultsKey.windowEdgeSnapEnabled)

```

## How Settings Changes Take Effect

Vorssaint-utils implements immediate configuration propagation through two mechanisms. First, SwiftUI views bind directly to `UserDefaults` values using property wrappers, ensuring UI components refresh automatically when underlying data changes. Second, background services such as `WindowLayoutService` subscribe to `UserDefaults.didChangeNotification` or poll values during event handling, allowing runtime behavior modification without restarts.

When you invoke `UserDefaults.standard.set(_:forKey:)`, the system writes to the macOS preferences domain `com.vorssaint.utils` immediately. This persistent storage ensures configuration survives application termination and system reboots, loading automatically on the next vorssaint-utils launch.

## Summary

- **Storage location**: All settings reside in `UserDefaults.standard` under the bundle identifier `com.vorssaint.utils`.
- **Key definitions**: The `DefaultsKey` enum in [`Sources/Vorssaint/Core/Defaults.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Defaults.swift) centralizes all valid configuration keys.
- **UI binding**: SwiftUI views in `Sources/Vorssaint/UI/Settings/` bind directly to UserDefaults for real-time synchronization.
- **Service integration**: Components like `WindowLayoutService` and `UpdateService` read defaults dynamically to drive behavior.
- **Programmatic access**: External Swift code can import Foundation and manipulate the same keys using standard `UserDefaults` API calls.
- **Immediate persistence**: Changes apply instantly and survive relaunches without additional code implementation.

## Frequently Asked Questions

### Where are vorssaint-utils settings saved on disk?

Vorssaint-utils writes configuration to the standard macOS `UserDefaults` system under the domain `com.vorssaint.utils`. macOS stores this data in a plist file within `~/Library/Preferences/`, though you should interact with these values through the `UserDefaults` API rather than editing the file directly to prevent corruption.

### Can I configure vorssaint-utils without opening the GUI?

Yes. Any Swift script or macOS application can modify vorssaint-utils settings by importing Foundation and calling `UserDefaults.standard.set(_:forKey:)` with the appropriate `DefaultsKey` values. Changes take effect immediately because the running vorssaint-utils process listens for UserDefaults notifications or polls values during operation.

### How do I reset vorssaint-utils to default settings?

Remove specific keys using `UserDefaults.standard.removeObject(forKey:)` with the target `DefaultsKey` enumeration member, or delete the entire `com.vorssaint.utils` domain from `~/Library/Preferences/com.vorssaint.utils.plist` while the application is closed. The next launch will regenerate defaults for any missing keys.

### Which file contains the UserDefaults keys for vorssaint-utils?

All UserDefaults keys are defined as static constants in **[`Sources/Vorssaint/Core/Defaults.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Defaults.swift)**. This file serves as the authoritative reference for every configurable option supported by the application, including booleans for feature toggles, strings for shortcuts, and string arrays for exclusion lists.