app.defaults - UserDefaults API

Read and write macOS application preferences (a native alternative to UserDefaults/defaults command).

Permission: Requires defaults declared in the manifest (L1 standard)

Methods

app.defaults.read(domain, key)

Read a preference value from the specified domain.

Parameters:

• domain (string) - Preferences domain (app Bundle ID or special domain name)
• key (string) - Key name

Returns: any|nil, error - Value or nil (if not exists); supports string/number/boolean/table

-- Read Finder settings
local showHidden = app.defaults.read("com.apple.finder", "AppleShowAllFiles")
app.log.info("Show hidden files: " .. tostring(showHidden))

-- Read Dock settings
local dockSize = app.defaults.read("com.apple.dock", "tilesize")
app.log.info("Dock icon size: " .. tostring(dockSize))

-- Read global settings
local darkMode = app.defaults.read("NSGlobalDomain", "AppleInterfaceStyle")
app.log.info("Appearance: " .. (darkMode or "Light"))

app.defaults.write(domain, key, value)

Write a preference value. Setting nil is equivalent to deleting the key.

Parameters:

• domain (string) - Preferences domain
• key (string) - Key name
• value (any) - Value (string/number/boolean/table/nil)

Returns: boolean, error

-- Show Finder hidden files
app.defaults.write("com.apple.finder", "AppleShowAllFiles", true)

-- Set a custom preference
app.defaults.write("com.example.myapp", "lastOpenPath", "/Users/test")

app.defaults.delete(domain, key)

Delete the specified key.

Parameters:

• domain (string) - Preferences domain
• key (string) - Key name

Returns: boolean, error

app.defaults.delete("com.apple.finder", "AppleShowAllFiles")

app.defaults.readAll(domain)

Read all preferences for the specified domain.

Parameters:

• domain (string) - Preferences domain

Returns: table, error - All key-value pairs

local all = app.defaults.readAll("com.apple.finder")
if all then
    for key, value in pairs(all) do
        app.log.info(key .. " = " .. tostring(value))
    end
end

Common Domains

Any application’s Bundle ID can be used as a domain to read its preferences.

Type Conversion

Examples

Toggle Finder Hidden Files

function MyPlugin:handleToggleHidden(context)
    local current = app.defaults.read("com.apple.finder", "AppleShowAllFiles")
    local newValue = not current

    app.defaults.write("com.apple.finder", "AppleShowAllFiles", newValue)

    -- Restart Finder to apply
    app.shell.execute("killall Finder")

    app.notification.show(
        "Finder Settings",
        newValue and "Hidden files are now visible" or "Hidden files are now hidden"
    )
end

Read Screenshot Settings

function MyPlugin:handleScreenshotInfo(context)
    local domain = "com.apple.screencapture"

    local location = app.defaults.read(domain, "location") or "~/Desktop"
    local fileType = app.defaults.read(domain, "type") or "png"
    local shadow = app.defaults.read(domain, "disable-shadow")

    local info = string.format(
        "Save location: %s\nFormat: %s\nWindow shadow: %s",
        location, fileType, shadow and "Off" or "On"
    )

    app.dialog.alert({title = "Screenshot Settings", message = info})
end

Backup and Restore App Preferences

function MyPlugin:handleBackupDefaults(context)
    local domain = "com.example.myapp"
    local all = app.defaults.readAll(domain)

    if not all then
        app.dialog.alert({title = "Error", message = "Unable to read preferences"})
        return
    end

    -- Export as JSON
    local json = app.json.stringify(all, true)
    local savePath = app.dialog.saveFile({
        title = "Export Preferences",
        nameFieldValue = domain .. ".json"
    })

    if savePath then
        app.file.write(savePath, json)
        app.notification.show("Export Complete", app.path.basename(savePath))
    end
end

Difference from app.settings

Notes

1. Permissions: Modifying system app preferences may require restarting the app to take effect
2. Sandbox Restrictions: Some system domains may not be writable from a sandbox
3. Use the Right Tool: Use app.settings to store plugin-specific configuration; use app.defaults to read/write other apps’ preferences
4. Data Formats: Data types are automatically converted to base64 strings; Date types are converted to Unix timestamps