hs

Last updated 3 months ago

Core Hammerspoon functionality

Submodules

API Overview

API Documentation

Constants

configdir

Signature

hs.configdir

Type

Constant

Description

A string containing Hammerspoon's configuration directory. Typically ~/.hammerspoon/

Signature

hs.docstrings_json_file

Type

Constant

Description

A string containing the full path to the docs.json file inside Hammerspoon's app bundle. This contains the full Hammerspoon API documentation and can be accessed in the Console using help("someAPI"). It can also be loaded and processed by the hs.doc extension

Signature

hs.processInfo

Type

Constant

Description

A table containing read-only information about the Hammerspoon application instance currently running.

Variables

Signature

hs.accessibilityStateCallback

Type

Variable

Description

An optional function that will be called when the Accessibility State is changed.

Notes

Signature

hs.completionsForInputString(completionWord) -> table of strings

Type

Variable

Description

Gathers tab completion options for the Console window

Parameters

Returns

Notes

Signature

hs.dockIconClickCallback

Type

Variable

Description

An optional function that will be called when the Hammerspoon Dock Icon is clicked while the app is running

Notes

Signature

hs.fileDroppedToDockIconCallback

Type

Variable

Description

An optional function that will be called when a files are dragged to the Hammerspoon Dock Icon or sent via the Services menu

Notes

Signature

hs.shutdownCallback

Type

Variable

Description

An optional function that will be called when the Lua environment is being destroyed (either because Hammerspoon is exiting or reloading its config)

Notes

Signature

hs.textDroppedToDockIconCallback

Type

Variable

Description

An optional function that will be called when text is dragged to the Hammerspoon Dock Icon or sent via the Services menu

Notes

Functions

Signature

hs.accessibilityState(shouldPrompt) -> isEnabled

Type

Function

Description

Parameters

Returns

Notes

Signature

hs.allowAppleScript([state]) -> bool

Type

Function

Description

Set or display whether or not external Hammerspoon AppleScript commands are allowed.

Parameters

Returns

Notes

Signature

hs.autoLaunch([state]) -> bool

Type

Function

Description

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

Parameters

Returns

Signature

hs.automaticallyCheckForUpdates([setting]) -> bool

Type

Function

Description

Gets and optionally sets the Hammerspoon option to automatically check for updates.

Parameters

Returns

Notes

Signature

hs.canCheckForUpdates() -> boolean

Type

Function

Description

Returns a boolean indicating whether or not the Sparkle framework is available to check for Hammerspoon updates.

Parameters

Returns

Notes

Signature

hs.checkForUpdates([silent]) -> none

Type

Function

Description

Check for an update now, and if one is available, prompt the user to continue the update process.

Parameters

Returns

Notes

Signature

hs.cleanUTF8forConsole(inString) -> outString

Type

Function

Description

Returns a copy of the incoming string that can be displayed in the Hammerspoon console. Invalid UTF8 sequences are converted to the Unicode Replacement Character and NULL (0x00) is converted to the Unicode Empty Set character.

Parameters

Returns

Notes

Signature

hs.closeConsole()

Type

Function

Description

Closes the Hammerspoon Console window

Parameters

Returns

Signature

hs.consoleOnTop([state]) -> bool

Type

Function

Description

Set or display whether or not the Hammerspoon console is always on top when visible.

Parameters

Returns

dockIcon

Signature

hs.dockIcon([state]) -> bool

Type

Function

Description

Set or display whether or not the Hammerspoon dock icon is visible.

Parameters

Returns

Notes

execute

Signature

hs.execute(command[, with_user_env]) -> output, status, type, rc

Type

Function

Description

Runs a shell command, optionally loading the users shell environment first, and returns stdout as a string, followed by the same result codes as os.execute would return.

Parameters

Returns

Notes

focus

Signature

hs.focus()

Type

Function

Description

Makes Hammerspoon the foreground app.

Signature

hs.getObjectMetatable(name) -> table or nil

Type

Function

Description

Fetches the Lua metatable for objects produced by an extension

Parameters

Returns

help

Signature

hs.help(identifier)

Type

Function

Description

Prints the documentation for some part of Hammerspoon's API and Lua 5.3. This function is actually sourced from hs.doc.help.

Parameters

Returns

Notes

hsdocs

Signature

hs.hsdocs([identifier])

Type

Function

Description

Display's Hammerspoon API documentation in a webview browser.

Parameters

Returns

Notes

loadSpoon

Signature

hs.loadSpoon(name[, global]) -> Spoon object

Type

Function

Description

Loads a Spoon

Parameters

Returns

Notes

Signature

hs.menuIcon([state]) -> bool

Type

Function

Description

Set or display whether or not the Hammerspoon menu icon is visible.

Parameters

Returns

open

Signature

hs.open(filePath)

Type

Function

Description

Opens a file as if it were opened with /usr/bin/open

Parameters

Returns

openAbout

Signature

hs.openAbout()

Type

Function

Description

Displays the OS X About panel for Hammerspoon; implicitly focuses Hammerspoon.

Signature

hs.openConsole([bringToFront])

Type

Function

Description

Opens the Hammerspoon Console window and optionally focuses it.

Parameters

Returns

Signature

hs.openConsoleOnDockClick([state]) -> bool

Type

Function

Description

Set or display whether or not the Console window will open when the Hammerspoon dock icon is clicked

Parameters

Returns

Notes

Signature

hs.openPreferences()

Type

Function

Description

Displays the Hammerspoon Preferences panel; implicitly focuses Hammerspoon.

Signature

hs.preferencesDarkMode([state]) -> bool

Type

Function

Description

Set or display whether or not the Preferences panel should display in dark mode.

Parameters

Returns

printf

Signature

hs.printf(format, ...)

Type

Function

Description

Prints formatted strings to the Console

Parameters

Returns

Notes

rawprint

Signature

hs.rawprint(aString)

Type

Function

Description

The original Lua print() function

Parameters

Returns

Notes

reload

Signature

hs.reload()

Type

Function

Description

Reloads your init-file in a fresh Lua environment.

showError

Signature

hs.showError(err)

Type

Function

Description

Shows an error to the user, using Hammerspoon's Console

Parameters

Returns

Notes

Signature

hs.toggleConsole()

Type

Function

Description

Toggles the visibility of the console

Parameters

Returns

Notes

Signature

hs.updateAvailable() -> string or false

Type

Function

Description

Gets the version number of an available update

Parameters

Returns

Notes

Signature

hs.uploadCrashData([state]) -> bool

Type

Function

Description

Get or set the "Upload Crash Data" preference for Hammerspoon

Parameters

Returns

Notes