AppleScript¶

DesktopRenamer's scripting dictionary is available to Script Editor after the app is installed. AppleScript is convenient for one-off commands, shell scripts, and automation tools that already support macOS scripting.

Use the structured records for typed read results. The commands on this page are the established text-command surface and remain available for compatibility. Window-specific commands are collected in window automation.

Quick start¶

tell application "DesktopRenamer"
    get api version
    get current space name
    get all spaces
end tell

get all spaces returns one line per space with fields separated by ~:

ManagedSpaceID~Name~DisplayName~Number~IsFullscreen~AppPath

The result is sorted by display and space number. Names and paths may be empty. The first field is macOS's ManagedSpaceID, not a persistent DesktopRenamer ID; it may change after display changes or Mission Control recreation, so refresh this result before using a legacy ID in a command. For persisted references, use the DesktopRenamer-owned IDs in structured AppleScript records.

The legacy text commands that accept a space ID—including switch to space, rename space, rearrange space, toggle lock space, and the window commands—expect a current ManagedSpaceID. They do not accept the persistent IDs from structured records. For mutations using persistent IDs, use the corresponding structured SpaceAPI operations where available.

This is the legacy text command. It is different from structured JSON-RPC getAllSpaces and get structured spaces: those return typed space records and include locked/isLocked state.

Space commands¶

tell application "DesktopRenamer"
    rename current space "Writing"
    switch to space "SPACE-ID"
    rename space "SPACE-ID" to "Research"
    rearrange space "SPACE-ID" direction "up"
    toggle lock space "SPACE-ID"
    restore moved windows
end tell

The direction parameter for rearrange space must be up or down.

Command	Parameters	Return / timing
`get api version`	—	Returns the API contract version immediately.
`get current space name`	—	Returns a string immediately.
`get current space id`	—	Returns current ManagedSpaceID values, comma-separated for multiple displays.
`get all spaces`	—	Returns the multiline space record described above.
`rename current space`	Text	Asynchronous; returns no value.
`rename space`	Space ID, `to` text	Asynchronous; returns no value.
`switch to space`	Space ID	Asynchronous; returns no value.
`rearrange space`	Space ID, `direction`	Asynchronous; moves one position.
`toggle lock space`	Space ID	Returns `true` after enabling or disabling Space Lock. Fullscreen spaces are rejected.
`restore moved windows`	—	Returns `true` after requesting restoration of windows moved by Space Lock.
`reload space labels`	—	Returns `true` after asking DesktopRenamer to reload its label windows.

The toggle commands return a Boolean containing the resulting state. toggle labels returns true only when both the active and preview labels are enabled. toggle desktop visibility changes the Keep visible on desktop preference for the labels.

Label and launcher commands¶

tell application "DesktopRenamer"
    toggle menubar
    toggle launcher
    toggle labels
    toggle active label
    toggle preview label
    toggle desktop visibility
    reload space labels
end tell

Errors and timing¶

Commands that change spaces or move windows return before the operating-system action has necessarily finished. execute window action waits for DesktopRenamer's action routine and returns true, but clients should still refresh window data after a state-changing command.

Validation errors use standard script errors:

Number	Meaning
`-1`	The API is disabled.
`-2`	An argument is missing or invalid.
`-3`	DesktopRenamer is not ready.

Invalid rearrangement directions set the script error to Direction must be up or down. Clients should inspect the script error number and string rather than treating every missing result as success. When the API is disabled, commands set script error -1 with API Disabled; read commands that have a text result also return that string, while Boolean commands return false.