Getting started

Switchboard turns something that happens on your Mac, such as a key press, a typed word or an app launching, into a macro that types, clicks and moves things. A macro is three rows: When it starts, Only if it should go ahead, and Do this.

Install and open it #

Switchboard is two programs that work together.

• Switchboard is the editor. You open it to build and read macros.

• Switchboard Engine is the part that listens for triggers and runs macros. It lives in the menu bar and has no windows.

Drag Switchboard to Applications and open it. The first time, the editor starts the engine for you. After that, if the engine is off (you chose Quit Switchboard from its menu), the editor shows a banner with a Start Engine button.

The Welcome sheet #

The first time you open the editor, a Welcome sheet appears. You can skip any part of it.

1. Let it work. The permission rows (below), each with an Allow… button. It opens the right pane of System Settings with Switchboard Engine already in the list, and a guide on the window shows which switch to turn on. A row shows Allowed once macOS has granted it, and the count shows how many of the two are on.

2. Run anything from the keyboard. The palette key, ⌥Space unless you change it.

3. Bring your library. Import from Keyboard Maestro or BetterTouchTool.

4. Make your first macro. Describe one for Make with AI, or start from an Example.

5. Done. Closes the sheet. Everything in it can be changed later in Settings (⌘,).

To see it again, use Show Welcome Again under Reset in Settings › Advanced.

Permissions #

Switchboard asks for two permissions up front. It asks for the rest only when a macro first needs them.

The permissions belong to Switchboard Engine, not to the editor, because the engine is the program that listens and clicks. In System Settings, switch on the engine's entry. The Permissions pane in Settings shows the same rows and their state.

Fn and Hyper #

Two modifiers are worth knowing before you pick hotkeys.

• Fn (the Globe key on newer keyboards) works as a modifier in a hotkey, so fn+cmd+t is a valid combination. The engine never swallows Fn on its own.

• Hyper means ⌘ ⌃ ⌥ ⇧ held together. Almost no other app uses it, so your own shortcuts rarely collide. In a key spec you write hyper+v.

If pressing the Globe key opens the emoji picker or dictation, set Press 🌐 key to to Do Nothing in System Settings > Keyboard, so it can serve as a modifier.

Switchboard can make Caps Lock your Hyper key (Library ▸ Remaps, or see Coming from Karabiner-Elements). Without that, press the four modifiers together.

See Keyboard shortcuts for the full key spec syntax.

Bring your library #

If you used Keyboard Maestro or BetterTouchTool, import first.

• File > Import… opens the same screen as the Welcome sheet.

• Choose a Keyboard Maestro library, a .kmmacros file, a BetterTouchTool .bttpreset export, or a .switchboard file.

• A review screen lists what will come across and what needs attention before anything is saved.

The Examples group #

A new library starts with a Group called Examples: macros that run on any Mac using only built-in steps. Open them to see how real macros are put together, or delete them. The ones to try first:

The group also holds Capture text, Click by letters, Hold to talk, and Keep awake for an hour. Three Examples are turned off until you turn them on, because they listen for the network or watch a folder and macOS asks before they can: the iPhone Shortcut webhook, the GitHub push webhook and the new-PDFs filer. Switchboard also adds groups for Quicklinks (type g in the palette to search Google), Clipboard actions, Selection bar, Thing actions, Drop targets and Browser. Browser macros are off until you install the browser extension.

The Examples use ⌃ ⌥ ⌘ together. No other app or macOS shortcut takes that combination, and you can press it without extra tools. If you have a Hyper key, ✦ works in its place: change the trigger to Hyper in the inspector.

Select one and press ⌥⌘R to dry run it. The result shows each step without clicking or typing anything. Then try the real hotkey in another app.

Where things live #

• Sidebar. Library views (All, Running, Recent, Favorites), your Groups, and Extensions.

• Macro list. The macros in the selected Group, with each macro's hotkey and the number of runs today.

• Detail. The selected macro as When, Only if and Do rows. Press ⌘⏎ to add a step.

• Inspector. The settings of the selected row, with the step's main field first and a completion list when you type {{ (see Variables and expressions). Show or hide it with ⌥⌘I.

• Activity (⌘2). Every run with its trace, and the events that did not start anything. See Debugging.

• Settings (⌘,). General, Account, Permissions, Automation, AI and Library.

• Library folder. Your macros are plain JSON files in ~/Library/Application Support/Switchboard/Library, one folder per Group. Settings › Advanced › Show in Finder opens it.

The menu bar glyph #

The engine shows a small switch icon in the menu bar. Its menu has:

• A status line (for example "Running · 7 macros") and the last run.

• A secure input row when it is on. See Triggers.

• Pause for 15 minutes and Pause for 1 hour, or Resume. While paused, no trigger starts a macro.

• Open Switchboard and Quit.

The icon changes with the state: a switch when running, a pause symbol when paused, a key when secure input holds your triggers. To hide it, turn off Show Switchboard in the menu bar in General settings.

The palette #

Settings > Palette has a Palette hotkey, ⌥Space by default, with a few other choices. The palette is the quick launcher. Press the hotkey from any app, type part of a macro's name and press ⏎ to run it. It never takes the keyboard away from the app you were in until a row sends you somewhere. Rows come from your macros (recent ones first), your extensions, and events that fired nothing; if nothing matches, a row offers to build the macro with Make with AI. ⌥⏎ dry runs, ⌘⏎ opens it in the editor, ⇧⌘D debugs it, ⎋ closes it. Apps open from the palette: type saf and press ⏎ and Safari opens; the apps you open most come first.

Uninstall #

1. Choose Quit Switchboard from the menu bar icon. Moving the app to the Trash does not stop the engine, which keeps running (and keeps your hotkeys) until you quit it or log out.

2. Drag Switchboard from Applications to the Trash.

3. To remove what Switchboard keeps for you, delete ~/Library/Application Support/Switchboard (your macros and history; copy the folder first if you want to keep them), then the settings and caches it leaves around it. Quit Switchboard first, or macOS writes the settings files back:

   • ~/Library/Preferences/com.payablesdesk.switchboard.plist and ~/Library/Preferences/com.payablesdesk.switchboard.engine.plist (the app's and the engine's settings)

   • ~/Library/Caches/com.payablesdesk.switchboard, ~/Library/Caches/com.payablesdesk.switchboard.engine and ~/Library/Caches/Switchboard (caches, and pictures kept by the Drop shelf)

   • ~/Library/HTTPStorages/com.payablesdesk.switchboard and ~/Library/WebKit/com.payablesdesk.switchboard.engine (web content its windows loaded)

   • ~/Library/Containers/com.payablesdesk.switchboard.safari, only if you turned on the Safari extension

4. In System Settings › Privacy & Security, select Switchboard Engine in each list (Accessibility, Input Monitoring, Screen Recording) and press the minus button. If you turned on Open at login, also remove it in General › Login Items.

5. Saved sign-ins and your account sit in Keychain Access under com.payablesdesk.switchboard.account and com.payablesdesk.switchboard.byok; delete them there to forget them.

Next steps #

• Your first macro

• Triggers

• Variables and expressions

• Keyboard shortcuts