Around the app

Every part of the Welcome sheet, the Examples group, the editor window, the menu bar panel and the palette, and how to bring a library from another app.

Keyboard Maestro: Getting Started

This page describes each part of Switchboard in turn. Getting started has the short version.

The Welcome sheet #

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

Let it work. The permission rows, 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.
Run anything from the keyboard. The palette key, ⌥Space unless you change it.
Bring your library. Import from Keyboard Maestro or BetterTouchTool.
Make your first macro. Describe one for Make with AI, or start from an Example.
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 in full #

Permission	What it lets Switchboard do
Accessibility	Click buttons, read windows and press menu items in other apps.
Input Monitoring	Hear your hotkeys, typed triggers and gestures.
Screen Recording (optional)	Find things on screen by their text or picture.
Automation	Ask other apps to do things (AppleScript, Shortcuts). Asked for when a macro first needs it.
Notifications	Tell you when a macro needs you or fails. Asked for when a macro first needs it.

The Permissions pane in Settings shows the same rows and their state.

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:

Macro	Starts with	Does
Window to left half	`⌃⌥⌘←`	Snaps the front window to the left half of the screen.
Window to right half	`⌃⌥⌘→`	Snaps the front window to the right half.
Clipboard to plain text	`⌃⌥⌘P`	Strips formatting from the clipboard.
Clean up the clipboard	`⌃⌥⌘U`	Fixes text copied from a web page or PDF: straight quotes, plain spaces, joined lines.
Paste as lowercase	`⌃⌥⌘L`	Asks for text and types it in lowercase.
Type today's date	`🌐⌘T`	Types today's date as `YYYY-MM-DD` where the cursor is.
;shrug	typing `;shrug`	Replaces `;shrug` with a shrug.

The group also holds Capture text, Click by letters, 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. See Fn and Hyper.

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 engine shows a small switch icon in the menu bar. Click it to open the panel:

A search box at the top. Type to filter your favorites, recent macros, extensions and tools, press ↓ and ↑ to move, Return to run, Esc to clear the box and then close. Search all macros for the text (or Return with no match) opens the palette with it.
Attention, only when something waits: questions from the Inbox, approvals, held runs, a failed last run (Fix with AI…, Show Log), a keyboard permission problem, a licence problem and secure input. See Triggers. Return never answers these; you click.
Live: a layer you are in, an outside agent controlling the Mac (Stop), Keep Awake holds, and runs showing progress, each with Stop (⌘. for the first).
Favorites and Recent macros, then extension items.
A row of tools: Clipboard History, Actions for This, Paste as…, Shelf (each only while its feature is on), States, Pause (15 minutes, 1 hour, until resumed, or Resume; while paused, no trigger starts a macro), New Macro and Record New Macro. Hover one for its shortcut.
A footer with a status dot and line (for example "Running · 7 macros") and the last run, then Activity, Settings (⌘,), Open Switchboard (⌘O) and Quit (⌘Q).

Right-click (or Control-click) the icon for the same things as a plain menu.

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.

If you chose Quit Switchboard from its menu, the engine stays off until you open the editor again; until then the editor shows a banner with a Start Engine button.

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.