hs.userdefaults
ModuleModule for storing small amounts of data that persists across Hammerspoon restarts.
Values are stored in a dedicated UserDefaults suite named "hs.userdefaults", kept
separate from the app's own preferences so it doesn't get confused with Hammerspoon's
own configuration when inspected with tools like the defaults command line utility.
JavaScript ↔ storage type mapping:
- JavaScript strings, numbers, booleans, arrays and objects round-trip directly
- JavaScript
Dateobjects round-trip directly (no special API required) - JavaScript
null/undefinedare not storable values; useclear()to remove a key
Because the suite is just a standard macOS preferences domain, it can also be inspected
and manipulated from the command line with the defaults tool:
# Read every value stored by hs.userdefaults
defaults read hs.userdefaults
# Read a single key
defaults read hs.userdefaults someKey
# Write a value from the command line
defaults write hs.userdefaults someKey "some value"
# Delete a key
defaults delete hs.userdefaults someKey
- Note: This suite is not encrypted on disk. Do not use it to store sensitive information such as passwords, API keys, or tokens.
Properties
This module has no properties.
Methods
hs.userdefaults.set(key, value) -> None
Store a value under the given key. The value persists across Hammerspoon restarts.
Values must be storable as a property list: strings, numbers, booleans, Dates,
arrays, or objects (which may themselves nest any of those types).
is rejected with a logged error and nothing is stored. JavaScript functions have
no property-list representation; if passed directly, or nested inside an array or
object, they are silently stored as an empty object.
Declaration
hs.userdefaults.set(key, value) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| key | string | The name of the setting |
| value | any | A string, number, boolean, Date, array, or object to store |
Returns
None
Notes
Passing a native object from another `hs.*` module (e.g. a timer or hotkey)
Example
hs.userdefaults.set("username", "chris")
hs.userdefaults.set("launchCount", 42)
hs.userdefaults.set("lastRun", new Date())hs.userdefaults.get(key) -> any
Retrieve a previously stored value.
Declaration
hs.userdefaults.get(key) -> anyParameters
| Name | Type | Description |
|---|---|---|
| key | string | The name of the setting |
Returns
any
The stored value, or null if nothing is stored under that key
Example
const username = hs.userdefaults.get("username")hs.userdefaults.clear(key) -> boolean
Delete a previously stored value.
Declaration
hs.userdefaults.clear(key) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| key | string | The name of the setting to remove |
Returns
boolean
true if a value existed and was removed, false if the key was not set
Example
hs.userdefaults.clear("username")hs.userdefaults.getKeys() -> string[]
Get the names of all currently stored settings.
Declaration
hs.userdefaults.getKeys() -> string[]Returns
string[]
An array of setting names
Example
console.log(hs.userdefaults.getKeys())hs.userdefaults.addWatcher(key, listener) -> None
Watch a key for changes.
Declaration
hs.userdefaults.addWatcher(key, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| key | string | The name of the setting to watch |
| listener | function | Called with the key and its new value whenever it changes |
Returns
None
Example
hs.userdefaults.addWatcher("username", (key, newValue) => {
console.log(key + " changed to " + newValue)
})hs.userdefaults.removeWatcher(key, listener) -> None
Remove a previously registered watcher.
Declaration
hs.userdefaults.removeWatcher(key, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| key | string | The name of the setting originally passed to `addWatcher` |
| listener | function | The function originally passed to `addWatcher` |
Returns
None
Example
hs.userdefaults.removeWatcher("username", myHandler)