Hammerspoon

https://www.hammerspoon.org/docs
Admin
Hammerspoon is a powerful macOS automation tool that allows users to control and customize their...
Tokens:263,866
Snippets:2,894
Trust Score:7.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### hs.task:start()

Source: https://www.hammerspoon.org/docs/hs.task.html

Starts the task.

```APIDOC
## hs.task:start()

### Description
Starts the task. If the task does not start successfully, the error message will be printed to the Hammerspoon Console.

### Returns
- **object/boolean** - Returns the task object if started successfully, otherwise returns false.
```

--------------------------------

### hs.httpserver.hsminweb:start

Source: https://www.hammerspoon.org/docs/hs.httpserver.hsminweb.html

Start the web server.

```APIDOC
## hs.httpserver.hsminweb:start()

### Description
Start serving pages for the hsminweb web server.

### Returns
- **hsminwebTable** - The hsminWebTable object.
```

--------------------------------

### hs.network.configuration:start()

Source: https://www.hammerspoon.org/docs/hs.network.configuration.html

Starts watching the store object for changes.

```APIDOC
## hs.network.configuration:start()

### Description
Starts watching the store object for changes to the monitored keys and invokes the callback function when a change occurs.

### Returns
- **storeObject** (object) - The store object.
```

--------------------------------

### hs.fs.volume:start()

Source: https://www.hammerspoon.org/docs/hs.fs.volume.html

Starts the volume watcher.

```APIDOC
## hs.fs.volume:start()

### Description
Starts the volume watcher.
```

--------------------------------

### start

Source: https://www.hammerspoon.org/docs/hs.audiodevice.watcher.html

Starts the audio device watcher.

```APIDOC
## hs.audiodevice.watcher.start()

### Description
Starts the audio device watcher to begin monitoring system audio events.
```

--------------------------------

### hs.httpserver:start

Source: https://www.hammerspoon.org/docs/hs.httpserver.html

Starts an HTTP server object.

```APIDOC
## hs.httpserver:start

### Description
Starts the HTTP server object.
```

--------------------------------

### hs.application.watcher:start()

Source: https://www.hammerspoon.org/docs/hs.application.watcher.html

Starts the application watcher to begin monitoring events.

```APIDOC
## hs.application.watcher:start()

### Description
Starts the application watcher.

### Returns
- **watcher** (hs.application.watcher) - The watcher object.
```

--------------------------------

### hs.eventtap:start

Source: https://www.hammerspoon.org/docs/hs.eventtap.html

Starts an event tap.

```APIDOC
## hs.eventtap:start()

### Description
Starts an event tap.

### Returns
- **eventtap** - The event tap object.
```

--------------------------------

### hs.pasteboard.watcher:start

Source: https://www.hammerspoon.org/docs/hs.pasteboard.watcher.html

Starts the pasteboard watcher.

```APIDOC
## hs.pasteboard.watcher:start() -> timer

### Description
Starts an hs.pasteboard.watcher object.

### Returns
- (timer) The hs.pasteboard.watcher object.
```

--------------------------------

### hs.spaces.watcher:start

Source: https://www.hammerspoon.org/docs/hs.spaces.watcher.html

Starts the Spaces watcher.

```APIDOC
## hs.spaces.watcher:start()

### Description
Starts the Spaces watcher.

### Returns
- **watcher** (hs.spaces.watcher) - The watcher object.
```

--------------------------------

### hs.doc.hsdocs.start()

Source: https://www.hammerspoon.org/docs/hs.doc.hsdocs.html

Starts the internal documentation web server.

```APIDOC
## hs.doc.hsdocs.start()

### Description
Start the Hammerspoon internal documentation web server.

### Returns
- **hs.doc.hsdocs** (table) - The table representing the module.
```

--------------------------------

### hs.axuielement.observer:start

Source: https://www.hammerspoon.org/docs/hs.axuielement.observer.html

Starts observing the application and triggers callbacks for assigned elements and notifications.

```APIDOC
## hs.axuielement.observer:start()

### Description
Start observing the application and trigger callbacks for the elements and notifications assigned. This method does nothing if the observer is already running.

### Returns
- **observerObject** - The observer object.
```

--------------------------------

### hs.screen.watcher:start

Source: https://www.hammerspoon.org/docs/hs.screen.watcher.html

Starts the screen watcher to begin monitoring for screen arrangement changes.

```APIDOC
## hs.screen.watcher:start() -> watcher

### Description
Starts the screen watcher, making it so the callback function is called each time the screen arrangement changes.

### Returns
- **watcher** (hs.screen.watcher) - The hs.screen.watcher object.
```

--------------------------------

### hs.usb.watcher:start

Source: https://www.hammerspoon.org/docs/hs.usb.watcher.html

Starts the USB watcher to begin monitoring for device events.

```APIDOC
## hs.usb.watcher:start() -> watcher

### Description
Starts the USB watcher.

### Returns
- **watcher** (hs.usb.watcher) - The watcher object.
```

--------------------------------

### hs.audiodevice:watcherStart

Source: https://www.hammerspoon.org/docs/hs.audiodevice.html

Starts the watcher for the hs.audiodevice object.

```APIDOC
## hs.audiodevice:watcherStart()

### Description
Starts the watcher on an hs.audiodevice object.

### Returns
- **hs.audiodevice or nil** - The hs.audiodevice object, or nil if an error occurred.
```

--------------------------------

### hs.camera.startWatcher

Source: https://www.hammerspoon.org/docs/hs.camera.html

Starts the camera devices watcher.

```APIDOC
## hs.camera.startWatcher()

### Description
Starts the camera devices watcher.
```

--------------------------------

### hs.noises:start

Source: https://www.hammerspoon.org/docs/hs.noises.html

Starts listening to the microphone and passing the audio to the recognizer.

```APIDOC
## hs.noises:start() -> self

### Description
Starts listening to the microphone and passing the audio to the recognizer.

### Returns
- **self** (hs.noises object) - The hs.noises object.
```

--------------------------------

### hs.wifi.watcher:start

Source: https://www.hammerspoon.org/docs/hs.wifi.watcher.html

Starts the SSID watcher to begin monitoring for Wi-Fi events.

```APIDOC
## hs.wifi.watcher:start()

### Description
Starts the SSID watcher.

### Returns
- **watcher** (hs.wifi.watcher) - The watcher object.
```

--------------------------------

### hs.network.reachability:start

Source: https://www.hammerspoon.org/docs/hs.network.reachability.html

Starts watching the reachability object for changes.

```APIDOC
## hs.network.reachability:start()

### Description
Starts watching the reachability object for changes and invokes the callback function (if any) when a change occurs.

### Returns
- **reachabilityObject** - The reachability object.
```

--------------------------------

### Configure and start hs.redshift

Source: https://www.hammerspoon.org/docs/hs.redshift.html

Initializes a window filter to disable redshift for specific apps and starts the redshift service with a defined schedule and transition duration.

```lua
-- make a windowfilterDisable for redshift: VLC, Photos and screensaver/login window will disable color adjustment and inversion
local wfRedshift=hs.window.filter.new({VLC={focused=true},Photos={focused=true},loginwindow={visible=true,allowRoles='*'}},'wf-redshift')
-- start redshift: 2800K + inverted from 21 to 7, very long transition duration (19->23 and 5->9)
hs.redshift.start(2800,'21:00','7:00','4h',true,wfRedshift)
-- allow manual control of inverted colors
hs.hotkey.bind(HYPER,'f1','Invert',hs.redshift.toggleInvert)
```

--------------------------------

### hs.uielement.watcher:start

Source: https://www.hammerspoon.org/docs/hs.uielement.watcher.html

Starts the watcher to monitor a specified list of events.

```APIDOC
## hs.uielement.watcher:start(events)

### Description
Tells the watcher to start watching for the given list of events.

### Parameters
- **events** (array) - An array of events to be watched for.

### Returns
- **hs.uielement.watcher** - The watcher object.
```

--------------------------------

### hs.speech.listener:start

Source: https://www.hammerspoon.org/docs/hs.speech.listener.html

Activates the speech recognizer.

```APIDOC
## hs.speech.listener:start()

### Description
Make the speech recognizer active.

### Returns
- **recognizerObject** - The speech recognizer object.
```

--------------------------------

### hs.pathwatcher:start

Source: https://www.hammerspoon.org/docs/hs.pathwatcher.html

Starts the monitoring process for an existing path watcher object.

```APIDOC
## hs.pathwatcher:start()

### Description
Starts the path watcher to begin monitoring the path defined during initialization.

### Returns
- **watcher** (hs.pathwatcher) - The path watcher object.
```

--------------------------------

### hs.spotlight:start

Source: https://www.hammerspoon.org/docs/hs.spotlight.html

Begin the gathering phase of a Spotlight query.

```APIDOC
## hs.spotlight:start()

### Description
Begin the gathering phase of a Spotlight query. If the query string is invalid, an error is logged and the query will not start.

### Returns
- **spotlightObject** (table) - The spotlightObject.
```

--------------------------------

### hs.battery.watcher:start

Source: https://www.hammerspoon.org/docs/hs.battery.watcher.html

Starts the battery watcher to begin monitoring for power state changes.

```APIDOC
## hs.battery.watcher:start() -> self

### Description
Starts the battery watcher.

### Returns
- **self** (hs.battery.watcher) - The hs.battery.watcher object.
```

--------------------------------

### hs.redshift.start

Source: https://www.hammerspoon.org/docs/hs.redshift.html

Sets the schedule and (re)starts the redshift module.

```APIDOC
## hs.redshift.start(colorTemp, nightStart, nightEnd[, transition[, invertAtNight[, windowfilterDisable[, dayColorTemp]]]])

### Description
Sets the schedule and (re)starts the module.

### Parameters
- **colorTemp** (number) - Required - Desired color temperature (Kelvin) during the night cycle.
- **nightStart** (string/number) - Required - Start time of the night cycle (HH:MM or seconds after midnight).
- **nightEnd** (string/number) - Required - End time of the night cycle (HH:MM or seconds after midnight).
- **transition** (string/number) - Optional - Duration of the transition.
- **invertAtNight** (boolean) - Optional - Whether to invert colors during the night.
- **windowfilterDisable** (hs.window.filter/table) - Optional - Window filter or list of apps to disable adjustment.
- **dayColorTemp** (number) - Optional - Desired color temperature during the day cycle.
```

--------------------------------

### hs.sound.getAudioEffectNames

Source: https://www.hammerspoon.org/docs/hs.sound.html

Gets a table of installed Audio Units Effect names.

```APIDOC
## hs.sound.getAudioEffectNames()

### Description
Gets a table of installed Audio Units Effect names.

### Returns
- **table** - A table containing the names of all installed Audio Units Effects.
```

--------------------------------

### Get Audio Effect Names

Source: https://www.hammerspoon.org/docs/hs.sound.html

Retrieves a table of installed Audio Units Effect names.

```lua
hs.inspect(hs.audiounit.getAudioEffectNames())
```

--------------------------------

### hs.razer.init

Source: https://www.hammerspoon.org/docs/hs.razer.html

Initializes the Razer driver and sets a discovery callback.

```APIDOC
## hs.razer.init(fn)

### Description
Initialises the Razer driver and sets a discovery callback. This function must be called before any other parts of this module are used.

### Parameters
- **fn** (function) - Required - A function that will be called when a Razer device is connected or disconnected.
```

--------------------------------

### hs.distributednotifications:start

Source: https://www.hammerspoon.org/docs/hs.distributednotifications.html

Starts the NSDistributedNotificationCenter watcher.

```APIDOC
## hs.distributednotifications:start()

### Description
Starts a NSDistributedNotificationCenter watcher.

### Returns
- The `hs.distributednotifications` object
```

--------------------------------

### hs.spaces.toggleLaunchPad()

Source: https://www.hammerspoon.org/docs/hs.spaces.html

Toggles the Launch Pad display.

```APIDOC
## hs.spaces.toggleLaunchPad()

### Description
Toggles the Launch Pad display, equivalent to the system Launch Pad gesture or touchbar icon.
```

--------------------------------

### Configure and Subscribe to Window Filters

Source: https://www.hammerspoon.org/docs/hs.window.filter.html

Examples of creating custom window filters, applying specific filtering rules, and subscribing to window events.

```lua
local wf=hs.window.filter

-- alter the default windowfilter
wf.default:setAppFilter('My IDE',{allowTitles=1}) -- ignore no-title windows (e.g. transient autocomplete suggestions) in My IDE

-- set the exact scope of what you're interested in - see hs.window.filter:setAppFilter()
wf_terminal = wf.new{'Terminal','iTerm2'} -- all visible terminal windows
wf_timewaster = wf.new(false):setAppFilter('Safari',{allowTitles='reddit'}) -- any Safari windows with "reddit" anywhere in the title
wf_leftscreen = wf.new{override={visible=true,fullscreen=false,allowScreens='-1,0',currentSpace=true}}
-- all visible and non-fullscreen windows that are on the screen to the left of the primary screen in the current Space
wf_editors_righthalf = wf.new{'TextEdit','Sublime Text','BBEdit'}:setRegions(hs.screen.primaryScreen():fromUnitRect'0.5,0/1,1')
-- text editor windows that are on the right half of the primary screen
wf_bigwindows = wf.new(function(w)return w:frame().area>3000000 end) -- only very large windows
wf_notif = wf.new{['Notification Center']={allowRoles='AXNotificationCenterAlert'}} -- notification center alerts

-- subscribe to events
wf_terminal:subscribe(wf.windowFocused,some_fn) -- run a function whenever a terminal window is focused
wf_timewaster:subscribe(wf.hasWindow,startAnnoyingMe):subscribe(wf.hasNoWindows,stopAnnoyingMe) -- fight procrastination :)
```

--------------------------------

### hs.camera:startPropertyWatcher()

Source: https://www.hammerspoon.org/docs/hs.camera.html

Starts the property watcher for the camera object.

```APIDOC
## hs.camera:startPropertyWatcher()

### Description
Starts the property watcher on a camera.

### Returns
- **hs.camera** - The camera object.
```

--------------------------------

### hs.spoons.list

Source: https://www.hammerspoon.org/docs/hs.spoons.html

Returns a list of installed or loaded Spoons.

```APIDOC
## hs.spoons.list() -> table

### Description
Return a list of installed/loaded Spoons.

### Parameters
- **onlyLoaded** (boolean) - Optional - If true, only return loaded Spoons. Defaults to false.

### Returns
- **table** - A list of spoons, where each entry contains name, loaded status, and version (if loaded).
```

--------------------------------

### hs.timer.delayed:start

Source: https://www.hammerspoon.org/docs/hs.timer.delayed.html

Starts or restarts the callback countdown.

```APIDOC
## hs.timer.delayed:start([delay])

### Description
Starts or restarts the callback countdown. If the timer is triggered again before the delay elapses, the countdown resets.

### Parameters
- **delay** (number) - Optional - If provided, sets the countdown duration for this specific invocation only.

### Returns
- **hs.timer.delayed object** - The delayed timer object.
```

--------------------------------

### hs.location.start()

Source: https://www.hammerspoon.org/docs/hs.location.html

Enables location update tracking for more precise location fixes.

```APIDOC
## hs.location.start()

### Description
Starts location tracking. When enabled, calculations based on the RSSI of visible WiFi networks are performed more frequently to provide a more precise location fix.
```

--------------------------------

### Configure highlight UI settings

Source: https://www.hammerspoon.org/docs/hs.window.highlight.html

Enable overlay mode and set the flash duration for window visibility changes.

```lua
hs.window.highlight.ui.overlay=true
```

```lua
hs.window.highlight.ui.flashDuration=0.3
```

--------------------------------

### Initialize MIDI Device and Callback

Source: https://www.hammerspoon.org/docs/hs.midi.html

Creates a new MIDI device instance and registers a callback function to handle and print incoming MIDI command metadata.

```lua
midiDevice = hs.midi.new(hs.midi.devices()[3])
midiDevice:callback(function(object, deviceName, commandType, description, metadata)
           print("object: " .. tostring(object))
           print("deviceName: " .. deviceName)
           print("commandType: " .. commandType)
           print("description: " .. description)
           print("metadata: " .. hs.inspect(metadata))
           end)
```

--------------------------------

### hs.caffeinate.watcher:start

Source: https://www.hammerspoon.org/docs/hs.caffeinate.watcher.html

Starts the watcher to begin monitoring for events.

```APIDOC
## hs.caffeinate.watcher:start()

### Description
Starts the sleep/wake watcher.

### Returns
- **watcher** (hs.caffeinate.watcher) - The watcher object.
```

--------------------------------

### hs.ipc.cliInstall

Source: https://www.hammerspoon.org/docs/hs.ipc.html

Installs the hs command line tool to the specified path.

```APIDOC
## hs.ipc.cliInstall([path][,silent])

### Description
Installs the `hs` command line tool. Defaults to installing in `/usr/local`.

### Parameters
- **path** (string) - Optional - Path to install the tool in.
- **silent** (boolean) - Optional - Whether or not to print errors to the Hammerspoon Console.

### Returns
- **bool** - True if the tool was successfully installed, otherwise false.
```

--------------------------------

### hs.application.open

Source: https://www.hammerspoon.org/docs/hs.application.html

Launches an application, or activates it if it's already running.

```APIDOC
## hs.application.open(app[, wait, [waitForFirstWindow]])

### Description
Launches an application or activates it if it is already running.

### Parameters
- **app** (string) - Required - The application name, full path, or bundle ID.
- **wait** (number) - Optional - Maximum seconds to wait for launch. Defaults to 0.
- **waitForFirstWindow** (boolean) - Optional - If true, waits until the app has spawned its first window.

### Returns
- **hs.application object** - The application object for the launched or activated application, or nil if not found.
```

--------------------------------

### hs.sound.systemSounds

Source: https://www.hammerspoon.org/docs/hs.sound.html

Gets a table of available system sounds.

```APIDOC
## hs.sound.systemSounds()

### Description
Gets a table of available system sounds.

### Returns
- **table** - A table containing all of the available sound files found in system sound directories.
```

--------------------------------

### hs.window.highlight.start

Source: https://www.hammerspoon.org/docs/hs.window.highlight.html

Starts the window highlighting module. You can optionally provide window filters to control when isolate or overlay modes are automatically triggered.

```APIDOC
## hs.window.highlight.start([windowfilterIsolate[, windowfilterOverlay]])

### Description
Starts the module. If windowfilterIsolate is provided, isolate mode is automatically enabled when a matching window is focused. If windowfilterOverlay is provided, it determines which windows trigger overlay mode.

### Parameters
- **windowfilterIsolate** (hs.window.filter or list of strings) - Optional - An hs.window.filter instance or list of application names to trigger isolate mode.
- **windowfilterOverlay** (hs.window.filter) - Optional - An hs.window.filter instance to determine windows for overlay mode.

### Returns
- None
```

--------------------------------

### Help Function Usage

Source: https://www.hammerspoon.org/docs/hs.doc.html

Examples of using the help function or its shorthand aliases to retrieve documentation for specific API components.

```lua
help("hs.reload")
help.hs.reload
lua._man._3_4_8
```

--------------------------------

### hs.timer:start

Source: https://www.hammerspoon.org/docs/hs.timer.html

Starts an hs.timer object. The timer will not call the callback immediately.

```APIDOC
## hs.timer:start()

### Description
Starts an hs.timer object.

### Returns
- **timer** (object) - The hs.timer object.
```

--------------------------------

### Configure and bind hs.expose instances

Source: https://www.hammerspoon.org/docs/hs.expose.html

Create various expose instances with custom filters and bind them to hotkeys for quick access.

```lua
-- set up your instance(s)
expose = hs.expose.new(nil,{showThumbnails=false}) -- default windowfilter, no thumbnails
expose_app = hs.expose.new(nil,{onlyActiveApplication=true}) -- show windows for the current application
expose_space = hs.expose.new(nil,{includeOtherSpaces=false}) -- only windows in the current Mission Control Space
expose_browsers = hs.expose.new{'Safari','Google Chrome'} -- specialized expose using a custom windowfilter
-- for your dozens of browser windows :)

-- then bind to a hotkey
hs.hotkey.bind('ctrl-cmd','e','Expose',function()expose:toggleShow()end)
hs.hotkey.bind('ctrl-cmd-shift','e','App Expose',function()expose_app:toggleShow()end)
```

--------------------------------

### hs.location.start()

Source: https://www.hammerspoon.org/docs/hs.location.html

Begins location tracking using OS X's Location Services.

```APIDOC
## hs.location.start()

### Description
Begins location tracking using OS X's Location Services so that registered callback functions can be invoked.

### Returns
- **boolean** - True if the operation succeeded, otherwise false.
```

--------------------------------

### hs.window.layout:start

Source: https://www.hammerspoon.org/docs/hs.window.layout.html

Puts the window layout instance into active mode for automatic management.

```APIDOC
## hs.window.layout:start() -> hs.window.layout object

### Description
Puts a window layout instance in "active mode". In this mode, the layout monitors window events and automatically re-applies rules when changes are detected.

### Returns
- **hs.window.layout** - The current layout object.
```

--------------------------------

### hs.network.ping.echoRequest:start

Source: https://www.hammerspoon.org/docs/hs.network.ping.echoRequest.html

Starts the echoRequestObject by resolving the server's address and beginning to listen for ICMP Echo Reply packets.

```APIDOC
## hs.network.ping.echoRequest:start()

### Description
Start the echoRequestObject by resolving the server's address and start listening for ICMP Echo Reply packets.

### Returns
- **echoRequestObject** - The echoRequestObject itself.
```

--------------------------------

### hs.bonjour.service:publish

Source: https://www.hammerspoon.org/docs/hs.bonjour.service.html

Begin advertising the specified local service.

```APIDOC
## hs.bonjour.service:publish([allowRename], [callback])

### Description
Begin advertising the specified local service. This method should only be called on serviceObjects created with hs.bonjour.service.new.

### Parameters
- **allowRename** (boolean) - Optional - Default true, specifies whether to automatically rename the service if a conflict occurs.
- **callback** (function) - Optional - A function that receives the serviceObject and a status string ("published" or "error").

### Returns
- **serviceObject** - The serviceObject.
```

--------------------------------

### Implement a basic HTTP client with hs.socket

Source: https://www.hammerspoon.org/docs/hs.socket.html

Demonstrates using socket tags to handle HTTP headers and content sequentially. Note that hs.http is recommended for production HTTP requests.

```lua
local TAG_HTTP_HEADER, TAG_HTTP_CONTENT = 1, 2
local body = ""
local function httpCallback(data, tag)
  if tag == TAG_HTTP_HEADER then
    print(tag, "TAG_HTTP_HEADER"); print(data)
    local contentLength = data:match("\r\nContent%-Length: (%d+)\r\n")
    client:read(tonumber(contentLength), TAG_HTTP_CONTENT)
  elseif tag == TAG_HTTP_CONTENT then
    print(tag, "TAG_HTTP_CONTENT"); print(data)
    body = data
  end
end

client = hs.socket.new(httpCallback):connect("google.com", 80)
client:write("GET /index.html HTTP/1.0\r\nHost: google.com\r\n\r\n")
client:read("\r\n\r\n", TAG_HTTP_HEADER)
```

--------------------------------

### Define layout command strings

Source: https://www.hammerspoon.org/docs/hs.window.layout.html

Examples of command strings used to define window layout rules, supporting shortened action names and pipe-separated sequences.

```lua
"move 1 [0,0,50,50] -1,0"
```

```lua
"max 0,0"
```

```lua
"move 1 foc [0,0,30,100] 0,0 | tile all foc [30,0,100,100] 0,0"
```

```lua
"1 new [0,0,50,100] 0,0 | 1 new [50,0,100,100] 0,0 | min"
```

--------------------------------

### hs.window.layout.new

Source: https://www.hammerspoon.org/docs/hs.window.layout.html

Creates a new hs.window.layout instance.

```APIDOC
## hs.window.layout.new(rules[, logname[, loglevel]])

### Description
Creates a new hs.window.layout instance.

### Parameters
- **rules** (table) - A table containing the rules for this windowlayout. If a special key `screens` is present, its value must be a valid screen configuration.
- **logname** (string, optional) - Name of the `hs.logger` instance for the new windowlayout.
- **loglevel** (string, optional) - Log level for the `hs.logger` instance.

### Returns
- **hs.window.layout object** - A new windowlayout instance.
```

--------------------------------

### hs.caffeinate.startScreensaver

Source: https://www.hammerspoon.org/docs/hs.caffeinate.html

Requests the system to start the screensaver.

```APIDOC
## hs.caffeinate.startScreensaver()

### Description
Request the system start the screensaver (which may lock the screen if the OS is configured to do so).
```

--------------------------------

### hs.spoons.isInstalled

Source: https://www.hammerspoon.org/docs/hs.spoons.html

Checks if a given Spoon is installed.

```APIDOC
## hs.spoons.isInstalled(name) -> table | nil

### Description
Check if a given Spoon is installed.

### Parameters
- **name** (string) - Required - Name of the Spoon to check.

### Returns
- **table | nil** - Returns a table with Spoon information if installed, otherwise nil.
```

--------------------------------

### hs.window.desktop()

Source: https://www.hammerspoon.org/docs/hs.window.html

Returns the desktop window object.

```APIDOC
## hs.window.desktop()

### Description
Returns the desktop "window" as an hs.window object.

### Returns
- **hs.window** - An hs.window object representing the desktop, or nil if Finder is not running.
```

--------------------------------

### hs.mjomatic.go(cfg)

Source: https://www.hammerspoon.org/docs/hs.mjomatic.html

Applies a configuration to the currently open windows based on a provided layout table.

```APIDOC
## hs.mjomatic.go(cfg)

### Description
Applies a configuration to the currently open windows. The configuration defines the shapes and positions of windows using a grid-based layout.

### Signature
`hs.mjomatic.go(cfg)`

### Parameters
- **cfg** (table) - Required - A table containing a series of strings representing the desired window layout and application mappings.

### Returns
- None

### Example
```lua
hs.mjomatic.go({
"CCCCCCCCCCCCCiiiiiiiiiii",
"CCCCCCCCCCCCCiiiiiiiiiii",
"SSSSSSSSSSSSSiiiiiiiiiii",
"SSSSSSSSSSSSSYYYYYYYYYYY",
"SSSSSSSSSSSSSYYYYYYYYYYY",
"",
"C Google Chrome",
"i iTerm",
"Y YoruFukurou",
"S Sublime Text 2"})
```
```

--------------------------------

### hs.window:title

Source: https://www.hammerspoon.org/docs/hs.window.html

Gets the title of the window.

```APIDOC
## hs.window:title()

### Description
Gets the title of the window.

### Returns
- **string** - A string containing the title of the window.
```

--------------------------------

### hs.window:subrole

Source: https://www.hammerspoon.org/docs/hs.window.html

Gets the subrole of the window.

```APIDOC
## hs.window:subrole()

### Description
Gets the subrole of the window, which helps determine if a window is a special kind, such as a modal or floating window.

### Returns
- **string** - A string containing the subrole of the window.
```

--------------------------------

### hs.window:size

Source: https://www.hammerspoon.org/docs/hs.window.html

Gets the size of the window.

```APIDOC
## hs.window:size()

### Description
Gets the current size of the window.

### Returns
- **table** - A size-table containing the width and height of the window.
```

--------------------------------

### Configure and Bind Window Switcher

Source: https://www.hammerspoon.org/docs/hs.window.switcher.html

Initialize different switcher instances with custom filters and bind them to hotkeys for navigation.

```lua
-- set up your windowfilter
switcher = hs.window.switcher.new() -- default windowfilter: only visible windows, all Spaces
switcher_space = hs.window.switcher.new(hs.window.filter.new():setCurrentSpace(true):setDefaultFilter{}) -- include minimized/hidden windows, current Space only
switcher_browsers = hs.window.switcher.new{'Safari','Google Chrome'} -- specialized switcher for your dozens of browser windows :)

-- bind to hotkeys; WARNING: at least one modifier key is required!
hs.hotkey.bind('alt','tab','Next window',function()switcher:next()end)
hs.hotkey.bind('alt-shift','tab','Prev window',function()switcher:previous()end)

-- alternatively, call .nextWindow() or .previousWindow() directly (same as hs.window.switcher.new():next())
hs.hotkey.bind('alt','tab','Next window',hs.window.switcher.nextWindow)
-- you can also bind to `repeatFn` for faster traversing
hs.hotkey.bind('alt-shift','tab','Prev window',hs.window.switcher.previousWindow,nil,hs.window.switcher.previousWindow)
```

--------------------------------

### hs.spoons.use(name, arg, [noerror])

Source: https://www.hammerspoon.org/docs/hs.spoons.html

Declaratively load and configure a Spoon.

```APIDOC
## hs.spoons.use(name, arg, [noerror])

### Description
Declaratively load and configure a Spoon.

### Signature
`hs.spoons.use(name, arg, [noerror]) -> boolean | nil`

### Parameters
- **name** (string) - Required - The name of the Spoon to load (without the .spoon extension).
- **arg** (table) - Optional - Configuration for the Spoon. Recognized keys:
  - **config** (table) - Variables to be stored in the Spoon object.
  - **hotkeys** (table|string) - Hotkey bindings to pass to the Spoon's bindHotkeys() method. Use "default" to use the Spoon's defaultHotkeys.
  - **fn** (function) - A function called with the loaded Spoon object as its first argument.
  - **loglevel** (string|number) - Value passed to the Spoon's logger.setLogLevel() method.
  - **start** (boolean) - If true, calls the Spoon's start() method after configuration.
- **noerror** (boolean) - Optional - If true, returns nil instead of logging an error if the Spoon is not installed.

### Returns
- **boolean | nil** - Returns true if the spoon was loaded, nil otherwise.
```

--------------------------------

### hs.window:screen

Source: https://www.hammerspoon.org/docs/hs.window.html

Gets the screen which the window is on.

```APIDOC
## hs.window:screen()

### Description
Gets the screen which the window is on. The returned screen represents the part of the window that remains visible if it spans multiple screens.

### Returns
- **hs.screen** - An hs.screen object representing the screen which contains the window.
```

--------------------------------

### hs.window:role

Source: https://www.hammerspoon.org/docs/hs.window.html

Gets the role of the window.

```APIDOC
## hs.window:role

### Signature
`hs.window:role() -> string`

### Description
Gets the role of the window.

### Returns
- **string** - A string containing the role of the window.
```

--------------------------------

### Documentation Output Example

Source: https://www.hammerspoon.org/docs/hs.doc.html

The output format displayed in the console when accessing a documentation object path.

```text
  Manipulate running applications

  [submodules]
  hs.application.watcher

  [subitems]
  hs.application:activate([allWindows]) -> bool
  hs.application:allWindows() -> window[]
      ...
  hs.application:visibleWindows() -> win[]
```

--------------------------------

### hs.window:otherWindowsSameScreen

Source: https://www.hammerspoon.org/docs/hs.window.html

Gets other windows on the same screen.

```APIDOC
## hs.window:otherWindowsSameScreen

### Signature
`hs.window:otherWindowsSameScreen() -> list of hs.window objects`

### Description
Gets other windows on the same screen.

### Returns
- **list** - A table of hs.window objects representing the visible windows other than this one that are on the same screen.
```

--------------------------------

### hs.vox.getUniqueID

Source: https://www.hammerspoon.org/docs/hs.vox.html

Gets the uniqueID of the current track.

```APIDOC
## hs.vox.getUniqueID()

### Description
Gets the uniqueID of the current track.

### Returns
- **string** - The name of the current track, or nil if an error occurred.
```

--------------------------------

### Create and Configure a Modal Environment

Source: https://www.hammerspoon.org/docs/hs.hotkey.modal.html

Initializes a new modal environment with a trigger hotkey and defines callbacks for entry, exit, and specific key bindings.

```lua
k = hs.hotkey.modal.new('cmd-shift', 'd')
function k:entered() hs.alert'Entered mode' end
function k:exited()  hs.alert'Exited mode'  end
k:bind('', 'escape', function() k:exit() end)
k:bind('', 'J', 'Pressed J',function() print'let the record show that J was pressed' end)
```

--------------------------------

### hs.websocket:status

Source: https://www.hammerspoon.org/docs/hs.websocket.html

Gets the status of a websocket.

```APIDOC
## hs.websocket:status()

### Description
Gets the status of a websocket.

### Returns
- **string** - Returns one of: connecting, open, closing, closed, or unknown.
```

--------------------------------

### Display a file or folder selection dialog with hs.dialog.chooseFileOrFolder

Source: https://www.hammerspoon.org/docs/hs.dialog.html

Opens a system panel for selecting files or folders, returning the selection or nil if cancelled.

```lua
hs.inspect(hs.dialog.chooseFileOrFolder("Please select a file:", "~/Desktop", true, false, true, {"jpeg", "pdf"}, true))
```

--------------------------------

### hs.bonjour.new

Source: https://www.hammerspoon.org/docs/hs.bonjour.html

Creates a new network service browser object.

```APIDOC
## hs.bonjour.new()

### Description
Creates a new network service browser that finds published services on a network using multicast DNS.

### Returns
- **browserObject** (object) - A new browser object or nil if an error occurs.
```

--------------------------------

### hs.vox.getAlbumArtist

Source: https://www.hammerspoon.org/docs/hs.vox.html

Gets the artist of the current album.

```APIDOC
## hs.vox.getAlbumArtist()

### Description
Gets the artist of current Album.

### Returns
- **string** - The artist of current Album, or nil if an error occurred.
```

--------------------------------

### hs.pasteboard.getContents

Source: https://www.hammerspoon.org/docs/hs.pasteboard.html

Gets the contents of the pasteboard as a string.

```APIDOC
## hs.pasteboard.getContents([name])

### Description
Gets the contents of the pasteboard.

### Parameters
- **name** (string) - Optional - The name of the pasteboard. Defaults to the system pasteboard.

### Returns
- (string or nil) - A string containing the contents of the pasteboard, or nil if an error occurred.
```

--------------------------------

### Display text input prompts

Source: https://www.hammerspoon.org/docs/hs.dialog.html

Examples of using hs.dialog.textPrompt with varying levels of configuration for buttons and secure input fields.

```lua
hs.dialog.textPrompt("Main message.", "Please enter something:")
```

```lua
hs.dialog.textPrompt("Main message.", "Please enter something:", "Default Value", "OK")
```

```lua
hs.dialog.textPrompt("Main message.", "Please enter something:", "Default Value", "OK", "Cancel")
```

```lua
hs.dialog.textPrompt("Main message.", "Please enter something:", "", "OK", "Cancel", true)
```

--------------------------------

### hs.spotify.getVolume

Source: https://www.hammerspoon.org/docs/hs.spotify.html

Gets the Spotify volume setting.

```APIDOC
## hs.spotify.getVolume()

### Description
Gets the Spotify volume setting.

### Returns
- A number containing the volume Spotify is set to between 1 and 100
```

--------------------------------

### hs.spotify.getCurrentTrackId

Source: https://www.hammerspoon.org/docs/hs.spotify.html

Gets the id of the current track.

```APIDOC
## hs.spotify.getCurrentTrackId()

### Description
Gets the id of the current track.

### Returns
- A string containing the id of the current track, or nil if an error occurred
```

--------------------------------

### Accessing Documentation via Console

Source: https://www.hammerspoon.org/docs/hs.doc.html

Create a documentation object to browse API documentation by appending the path to the desired module or function.

```lua
  doc = require("hs.doc")
  doc.hs.application
```

--------------------------------

### hs.spotify.getCurrentTrack

Source: https://www.hammerspoon.org/docs/hs.spotify.html

Gets the name of the current track.

```APIDOC
## hs.spotify.getCurrentTrack()

### Description
Gets the name of the current track.

### Returns
- A string containing the name of the current track, or nil if an error occurred
```

--------------------------------

### Create a new MIDI object

Source: https://www.hammerspoon.org/docs/hs.midi.html

Initializes a new hs.midi object using the name of the first available physical device.

```lua
hs.midi.new(hs.midi.devices()[1])
```

--------------------------------

### hs.mouse.scrollDirection()

Source: https://www.hammerspoon.org/docs/hs.mouse.html

Gets the system-wide direction of scrolling.

```APIDOC
## hs.mouse.scrollDirection()

### Description
Gets the system-wide direction of scrolling.

### Signature
`hs.mouse.scrollDirection() -> string`

### Returns
- **string** (string) - Either "natural" or "normal".
```

--------------------------------

### hs.expose.new

Source: https://www.hammerspoon.org/docs/hs.expose.html

Creates a new hs.expose instance with optional window filtering and UI preferences.

```APIDOC
## hs.expose.new([windowfilter[, uiPrefs][, logname, [loglevel]]])

### Description
Creates a new hs.expose instance. It can use a windowfilter to determine which windows to show.

### Parameters
- **windowfilter** (table/instance) - Optional - If omitted or nil, use the default windowfilter; otherwise it must be a windowfilter instance or constructor table.
- **uiPrefs** (table) - Optional - A table to override UI preferences for this instance.
- **logname** (string) - Optional - Name of the hs.logger instance.
- **loglevel** (string/number) - Optional - Log level for the logger.

### Returns
- **hs.expose object** - The new instance.
```

--------------------------------

### hs.keycodes.currentMethod()

Source: https://www.hammerspoon.org/docs/hs.keycodes.html

Get current input method.

```APIDOC
## hs.keycodes.currentMethod()

### Description
Get current input method.

### Returns
- **string|nil** - Name of current input method, or nil.
```

--------------------------------

### Create and use a logger instance

Source: https://www.hammerspoon.org/docs/hs.logger.html

Initializes a new logger with a specific ID and log level, then logs an info message. Note that dot syntax must be used instead of colon syntax for logger methods.

```lua
local log = hs.logger.new('mymodule','debug')
log.i('Initializing') -- will print "[mymodule] Initializing" to the console
```

--------------------------------

### hs.itunes.getCurrentTrack

Source: https://www.hammerspoon.org/docs/hs.itunes.html

Gets the name of the current track.

```APIDOC
## hs.itunes.getCurrentTrack()

### Description
Gets the name of the current track.

### Returns
- string or nil: A string containing the name of the current track, or nil if an error occurred.
```

--------------------------------

### hs.autoLaunch

Source: https://www.hammerspoon.org/docs/hs.html

Set or display the 'Launch on Login' status for Hammerspoon.

```APIDOC
## hs.autoLaunch([state])

### Description
Set or display the 'Launch on Login' status for Hammerspoon.

### Parameters
- **state** (boolean) - Optional. Sets whether Hammerspoon should be launched automatically when you log into your computer.

### Returns
- **boolean** - True if Hammerspoon is currently set to launch on login, otherwise False.
```

--------------------------------

### hs.itunes.getCurrentArtist

Source: https://www.hammerspoon.org/docs/hs.itunes.html

Gets the name of the current Artist.

```APIDOC
## hs.itunes.getCurrentArtist()

### Description
Gets the name of the current Artist.

### Returns
- string or nil: A string containing the Artist of the current track, or nil if an error occurred.
```

--------------------------------

### hs.itunes.getCurrentAlbum

Source: https://www.hammerspoon.org/docs/hs.itunes.html

Gets the name of the current Album.

```APIDOC
## hs.itunes.getCurrentAlbum()

### Description
Gets the name of the current Album.

### Returns
- string or nil: A string containing the Album of the current track, or nil if an error occurred.
```

--------------------------------

### Define a window layout

Source: https://www.hammerspoon.org/docs/hs.layout.html

Example of a layout table defining window positions and sizes for specific applications across different screens.

```lua
layout1 = {
    {"Mail", nil, "Color LCD", hs.layout.maximized, nil, nil},
    {"Safari", nil, "Thunderbolt Display", hs.layout.maximized, nil, nil},
    {"iTunes", "iTunes", "Color LCD", hs.layout.maximized, nil, nil},
    {"iTunes", "MiniPlayer", "Color LCD", nil, nil, hs.geometry.rect(0, -48, 400, 48)},
  }
```

--------------------------------

### hs.fs.tagsGet

Source: https://www.hammerspoon.org/docs/hs.fs.html

Gets the Finder tags of a file.

```APIDOC
## hs.fs.tagsGet(filepath)

### Description
Gets the Finder tags of a file.

### Parameters
- **filepath** (string) - Required - A string containing the path of a file

### Returns
- A table containing the list of the file's tags, or nil if the file has no tags assigned; throws a lua error if an error accessing the file occurs
```

--------------------------------

### Create and use pasteboard watchers

Source: https://www.hammerspoon.org/docs/hs.pasteboard.watcher.html

Demonstrates initializing watchers for the general and a named pasteboard, then writing content to them to trigger the callbacks.

```lua
generalPBWatcher = hs.pasteboard.watcher.new(function(v) print(string.format("General Pasteboard Contents: %s", v)) end)
specialPBWatcher = hs.pasteboard.watcher.new(function(v) print(string.format("Special Pasteboard Contents: %s", v)) end, "special")
hs.pasteboard.writeObjects("This is on the general pasteboard.")
hs.pasteboard.writeObjects("This is on the special pasteboard.", "special")
```

--------------------------------

### hs.fs.symlinkAttributes

Source: https://www.hammerspoon.org/docs/hs.fs.html

Gets the attributes of a symbolic link.

```APIDOC
## hs.fs.symlinkAttributes(filepath [, aname])

### Description
Gets the attributes of a symbolic link.

### Parameters
- **filepath** (string) - Required - A string containing the path of a link to inspect
- **aname** (string) - Optional - An optional attribute name. If this value is specified, only the attribute requested, is returned

### Returns
- A table or string if the values could be found, otherwise nil and an error string.
```

--------------------------------

### hs.network.configuration.open

Source: https://www.hammerspoon.org/docs/hs.network.configuration.html

Opens a session to the dynamic store maintained by the System Configuration server.

```APIDOC
## hs.network.configuration.open()

### Description
Opens a session to the dynamic store maintained by the System Configuration server.

### Returns
- **storeObject** (object) - The store object used for subsequent operations.
```

--------------------------------

### hs.deezer.getVolume()

Source: https://www.hammerspoon.org/docs/hs.deezer.html

Gets the deezer volume setting.

```APIDOC
## hs.deezer.getVolume()

### Description
Gets the deezer volume setting.

### Returns
- A number containing the volume deezer is set to between 1 and 100
```

--------------------------------

### Configure Custom Grid Hints

Source: https://www.hammerspoon.org/docs/hs.grid.html

Define a custom 16-column grid layout and assign specific keyboard keys to grid cells for the interactive resizing interface.

```lua
hs.grid.setGrid('16x4')
hs.grid.HINTS={
    {'f1', 'f2' , 'f3' , 'f4' , 'f5', 'f6', 'f7', 'f8', 'f9', 'f10', 'f11', 'f12', 'f13', 'f14', 'f15', 'f16'},
    {'1' , 'f11', 'f15', 'f19', 'f3', '=' , ']' , '2' , '3' , '4'  , '5'  , '6'  , '7'  , '8'  , '9'  , '0'  },
    {'Q' , 'f12', 'f16', 'f20', 'f4', '-' , '[' , 'W' , 'E' , 'R'  , 'T'  , 'Y'  , 'U'  , 'I'  , 'O'  , 'P'  },
    {'A' , 'f13', 'f17', 'f1' , 'f5', 'f7', '\', 'S' , 'D' , 'F'  , 'G'  , 'H'  , 'J'  , 'K'  , 'L'  , ','  },
    {'X' , 'f14', 'f18', 'f2' , 'f6', 'f8', ';' , '/' , '.' , 'Z'  , 'X'  , 'C'  , 'V'  , 'B'  , 'N'  , 'M'  }
}
```

--------------------------------

### hs.deezer.getCurrentTrack()

Source: https://www.hammerspoon.org/docs/hs.deezer.html

Gets the name of the current track.

```APIDOC
## hs.deezer.getCurrentTrack()

### Description
Gets the name of the current track.

### Returns
- A string containing the name of the current track, or nil if an error occurred
```

--------------------------------

### hs.grid.show

Source: https://www.hammerspoon.org/docs/hs.grid.html

Shows the grid and starts the modal interactive resizing process for the focused or frontmost window.

```APIDOC
## hs.grid.show([exitedCallback][, multipleWindows])

### Description
Shows the grid and starts the modal interactive resizing process for the focused or frontmost window.

### Parameters
- **exitedCallback** (function) - Optional - A function that will be called after the user dismisses the modal interface.
- **multipleWindows** (boolean) - Optional - If true, the resizing grid won't automatically go away after selecting the desired cells for the frontmost window; instead, it'll switch to the next window.
```

--------------------------------

### hs.hints.windowHints

Source: https://www.hammerspoon.org/docs/hs.hints.html

Displays a keyboard hint for switching focus to each window. Users can optionally provide a list of windows, a callback function, and a flag to include non-standard windows.

```APIDOC
## hs.hints.windowHints([windows, callback, allowNonStandard])

### Description
Displays a keyboard hint for switching focus to each window.

### Parameters
- **windows** (table) - Optional. A table containing `hs.window` objects. If nil, all windows are hinted.
- **callback** (function) - Optional. A function called when a window is selected, receiving the chosen `hs.window` object as an argument.
- **allowNonStandard** (boolean) - Optional. If true, includes all windows, not just standard ones.

### Returns
- None
```

--------------------------------

### hs.window.switcher:next

Source: https://www.hammerspoon.org/docs/hs.window.switcher.html

Shows the switcher instance (if not yet visible) and selects the next window.

```APIDOC
## hs.window.switcher:next()

### Description
Shows the switcher instance (if not yet visible) and selects the next window. The switcher will be dismissed and the selected window focused when all modifier keys are released.
```

--------------------------------

### hs.axuielement.axtextmarker:startMarker

Source: https://www.hammerspoon.org/docs/hs.axuielement.axtextmarker.html

Returns the starting marker for an axTextMarkerRangeObject.

```APIDOC
## hs.axuielement.axtextmarker:startMarker()

### Description
Returns the starting marker for an axTextMarkerRangeObject.

### Returns
- **axTextMarkerObject | nil** - The starting marker or nil if an error occurs.
- **errorString** - The error message if the operation fails.
```

--------------------------------

### hs.styledtext.fontNames

Source: https://www.hammerspoon.org/docs/hs.styledtext.html

Returns the names of all installed fonts for the system.

```APIDOC
## hs.styledtext.fontNames() -> table

### Description
Returns the names of all installed fonts for the system.

### Returns
- **table** - A table containing the names of every font installed for the system.
```

--------------------------------

### hs.expose:show

Source: https://www.hammerspoon.org/docs/hs.expose.html

Displays the expose interface with modal keyboard hints.

```APIDOC
## hs.expose:show([activeApplication])

### Description
Shows an expose-like screen with modal keyboard hints for switching to, closing or minimizing/unminimizing windows.

### Parameters
- **activeApplication** (boolean) - Optional - If true, only show windows of the active application; otherwise show all windows allowed by the instance windowfilter.
```

--------------------------------

### hs.window:windowsToNorth

Source: https://www.hammerspoon.org/docs/hs.window.html

Gets all windows to the north of this window.

```APIDOC
## hs.window:windowsToNorth([candidateWindows[, frontmost[, strict]]])

### Description
Gets all windows to the north of this window.

### Parameters
- **candidateWindows** (list) - Optional - A list of candidate windows to consider.
- **frontmost** (boolean) - Optional - If true, unoccluded windows are placed before occluded ones.
- **strict** (boolean) - Optional - If true, only consider windows at an angle between 45° and -45°.

### Returns
- **list** - A list of hs.window objects positioned north of the window.
```

--------------------------------

### hs.bonjour.service.new

Source: https://www.hammerspoon.org/docs/hs.bonjour.service.html

Creates a new serviceObject for advertising a service provided by the local computer.

```APIDOC
## hs.bonjour.service.new(name, service, port, [domain])

### Description
Returns a new serviceObject for advertising a service provided by your computer.

### Parameters
- **name** (string) - Required - The name of the service being advertised.
- **service** (string) - Required - The service type in the format '_service._protocol.' (e.g., '_http._tcp.').
- **port** (integer) - Required - The TCP or UDP port the service is provided at.
- **domain** (string) - Optional - The domain to advertise the service in.

### Returns
- **serviceObject** (object) - The newly created service object, or nil if there was an error.
```
Tokens:
Raw