Documentation

Guides

• Getting startedInstall Switchboard, finish the first-run Welcome, grant the two permissions it needs and see where to go next.
• Your first macroMake ;addr type your full address in any app, try it, turn it off and on, and change it. No code and no settings to learn.
• You can't break anythingWhat keeps your Mac safe while you learn: Try It, Undo, the On switch, Pause, Recently Deleted and History.
• GlossaryThe words these help pages use, from macro and trigger to locator and kit, one or two plain sentences each.
• A macro that works something outBuild a macro from scratch with a hotkey, a variable, an expression and a condition, dry run it, run it, and read its trace.
• Around the appEvery 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.
• Adding a trigger, condition or stepOne chooser adds every kind of block. Pick what it's about, then what to do with it, or type to search everything.
• Macros to addFour ready-made macros for error dialogs, form fields and the Inbox. Each one is turned off until you add it and choose to turn it on.
• Keyboard shortcutsEvery keyboard shortcut in Switchboard's menus and panels, and the key spec syntax used by Press keys and hotkey triggers.
• PrivacyLists exactly what stays on your Mac, what goes to iCloud, what a shared macro leaves out, what the AI features send, and what an agent can see.
• Security and team policyWhat leaves a managed Mac, what policy blocks, and how to export audit records.
• Deploying SwitchboardTeam seats, managed preferences, offline licences and the permissions a managed Mac still needs.
• Company sign-in and SCIMConfigure OIDC, verify a domain, provision people with SCIM and keep the owner's sign-in available.
• The team libraryRead company macros from a shared folder or git source, copy one to edit, and publish with your own credentials.
• UninstallingQuit the engine, remove the app, and delete the macros, settings, caches, permissions and Keychain items Switchboard keeps.
• Type your email addressType ;mail in any app and Switchboard types your email address in its place.
• Open an app with a keyPress ⌃⌥⌘N in any app and Notes comes to the front, opening it first if it isn't running.
• Hide everything but the front appPress ⌃⌥⌘H and every other app's windows go out of sight, leaving only the app you're working in.
• A reminder at a set timeEvery weekday at 4:30 PM a notification reminds you to stand up and stretch.
• Quiet the Mac when a meeting startsWhen Zoom opens, Switchboard quits Music and Messages so nothing plays or chimes during the call.
• Plug in before it's too lateWhen the battery drops below 20% and the Mac isn't plugged in, Switchboard tells you to plug in.
• Sort Downloads as things landReceipts and invoices leave Downloads for a dated folder in Documents, and pictures move to Pictures with a tag.
• Open your morning appsPress ⌃⌥⌘M and Mail, Calendar and Reminders open, one after the other.
• TriggersEvery way a macro can start, how conflicts and scopes decide which macro runs, and how to find out why a trigger did not fire.
• Triggers that watch: becomes true, States, waiting runsTurn any condition into a trigger, name situations as States, scope groups to them, and park runs that wait for a time or a condition.
• Limits on any triggerTick a box instead of writing counters and conditions: the first time each day, every 3rd time, twice within 2 seconds, a cooldown, only while you are at the Mac, only on one Mac, only in a State.
• Run a macro laterStart any macro at a time you type the way you say it, see everything scheduled in Upcoming, get a heads-up first, and use keys, the Later block and the late rules to make timers.
• Variables and expressionsUse {{ }} templates, variables, operators and built-in functions to make a macro's steps depend on data.
• FunctionsShows how to make a macro that other macros call, with inputs and a result, and how to pull repeated steps out into one.
• Thing typesEvery kind of thing Switchboard recognizes (link, email address, phone number, date, address, file, tracking number, git commit, color, code, JSON, measurement, IBAN, UUID, Mail message, image, text) and the fields each carries.
• Recording a macroWhat the Recorder writes down when you click, choose a menu command, switch apps or copy and paste, and how to record a fix into the middle of a macro.
• Make with AIDescribe a macro in a sentence and read what Claude wrote before anything is added or run.
• The menu bar panel and macro widgetsClick the menu bar glyph for a panel of what this moment can do; a macro with a panel field puts a button, toggle, readout or slider there while its Only-if list holds.
• Fn and HyperTwo modifiers worth knowing before you pick hotkeys. Fn (the Globe key) works in a hotkey, and Hyper is all four modifiers at once.
• Testing a macroShows how to save a run as a test, run tests and checks, and know a macro still works after an edit or a macOS update.
• DebuggingHow to find out why a macro did not run, why it failed and what it would do, using Activity, traces, dry runs and the command line.
• Guardrails: check before it happensStop a send, a quit or a push at the last second. A macro checks first, then lets the key through, blocks it, or asks "Send anyway?". Five ready-made ones.
• Troubleshooting permissionsExplains the five permissions Switchboard can ask for, what each one unlocks, and how to fix hotkeys or clicks that stop working.
• SnippetsType a short abbreviation and Switchboard replaces it with a longer text: fields to fill in, a caret position, the date, the clipboard.
• Quicklinks and keywordsGive any macro a one-word keyword in the palette, so "gh swift actors" opens a GitHub search; File > New Quicklink makes one in a sheet, and fallback searches appear when nothing matches.
• Clipboard actionsPress ⌘K on a copied item in the clipboard panel to transform it or act on it with your own macros: clean a link, reformat a color, pretty-print JSON, rewrite with AI.
• Paste asHold the Clipboard History key instead of pressing ⌘V to paste the clipboard as plain text, Markdown, JSON, text from an image or a file, with a live preview, or have AI rewrite it on the way in.
• The selection barSelect text in any app and a slim bar of icons appears above it: Copy, Search, Open link, Rewrite, Paste as, and any macro you make. Every icon is a macro that takes the selection.
• Act on what you're looking atOne hotkey shows the actions for whatever you are on (selected text, a file, a link, a ticket number, a tracking number) and runs your own macros on it. Teach Switchboard types of your own.
• Finding things on screenHow Switchboard finds a button, field or picture in another app, how sure it has to be, and what it does when it cannot find it.
• Read what an app showsTake the rows of a list, the whole text of a document, the links and the images out of any app's window, and run a macro when an element changes.
• Use your apps' actionsEvery Mac app that has Shortcuts actions shows up in Switchboard as steps, conditions and palette rows, with nothing for the app to do.
• Shortcuts, Siri and SpotlightRun, rehearse and manage your macros from the Shortcuts app, Siri and Spotlight on the Mac, including an extension's own actions.
• Services and URL schemesEvery app's Services menu entries and URL addresses become steps, and apps that answer back (x-callback-url) work in both directions.
• App KitsAdd a suite of features around a Mac app you don't own (its unread count as a value, buttons pinned to its window, a drawer, menu shortcuts, settings presets) that looks like the app made it.
• Kits inside Electron appsRun a kit's styles, features and commands inside Slack, VS Code, Notion or any other Electron app by opening the app through Switchboard.
• Safari and ChromeConnect your browser to Switchboard, then start macros from pages, change pages, and let page buttons run macros and get the result.
• Site KitsAdd a suite of features to a website you don't own (a button, a badge, a sidebar, commands) that looks like the site built it, and keeps working when the site changes.
• Use any web APIPaste an OpenAPI or GraphQL address and every endpoint becomes a step with a form; the token stays in your Keychain.
• Sign in to Google APIsSave a named Google (OAuth 2) sign-in once, then let any http step call a Google API as that account, with the token renewed for you.
• Agents and MCPHow Claude Code, Claude Desktop, Cursor and other agents run the macros you choose, with approval, a rate limit and a trace for every run.
• Trigger on anything an MCP server knowsRun a macro when a pull request, an issue, a database row or any other MCP resource changes, with no code for the service.
• AI budgetsSee what AI steps cost, set a monthly cap and a daily cap per macro, and write macros that stop or take a cheaper path when the budget is gone.
• The InboxQuestions macros park instead of popping up a window, and where to answer them: the menu bar, the iPhone and the command line.
• iPhone and Apple WatchDescribes what the iPhone and Apple Watch apps do: a Pad of tiles that run macros on your Mac, Sensors that start them, Approvals you answer from your wrist or pocket, and the Shortcuts, widget and Control Center actions that go with them.
• Several MacsRun a macro on another of your Macs from a hotkey, the palette or a Run macro step, over Bonjour on the same network or through iCloud, and what happens while that Mac sleeps.
• Coming from Keyboard MaestroHow Keyboard Maestro's groups, triggers, actions, conditions, variables and tokens map to Switchboard, and how to import your library.
• Coming from BetterTouchToolHow every BetterTouchTool trigger and action maps to Switchboard, what runs in the Window extension, and what the import records or leaves out.
• Coming from AlfredHow Alfred's workflows, keywords, script filters, web searches and feature hotkeys map to Switchboard, and what the import keeps, notes or leaves out.
• Coming from RaycastHow Raycast's script commands, quicklinks, snippets and extensions map to Switchboard, and the hotkeys Raycast keeps encrypted.
• Coming from LaunchBarHow a LaunchBar action becomes a macro with a palette keyword, which parts of LaunchBar's JavaScript API Switchboard provides, and what stays behind.
• Coming from TextExpander or AlfredImport snippets from TextExpander, Alfred, Raycast or macOS Text Replacements, and how their placeholders map to Switchboard's snippet tokens.
• Coming from HazelHow Hazel's folders, rules, conditions and actions map to Switchboard, and what the import keeps, notes or leaves out.
• Coming from Karabiner-ElementsHow Karabiner-Elements remaps, dual-role keys, layers and complex modifications map to Switchboard, and what the import keeps, notes or leaves out.
• Coming from Automator and ShortcutsHow Quick Actions, workflows, folder actions and Shortcuts become macros, which Automator actions turn into steps, and what still runs through Automator itself.
• Writing an extensionBuild a TypeScript extension that adds actions, conditions, triggers, functions or palette rows, and asks only for the permissions it needs.
• Make your first extensionA ten-minute walk-through from an empty folder to a working extension action in a macro, with hot reload, a setting, a permission, logs, tests and the gallery.
• Making an extension with AIDescribe an extension in a sentence, read the checked TypeScript Claude wrote and the permissions it asks for, try it, and install it in Develop mode.
• Turn a command-line tool into stepsPoint Switchboard at any command-line tool and its --help becomes steps with real forms; review them before they are saved.
• kit.jsonEvery key of a Site Kit's kit.json (id, version, permissions, anchors, settings, palette, sidebar, theme), and the group's site, with what each does.
• The kit page APIEvery call a Site Kit's JavaScript can make: route, place, anchor, onResponse, store, settings, command, sidebar, toast, ui.upgrade and theme.

Reference