Documentation

Guides

• Getting startedInstall Switchboard, finish the first-run Welcome, grant the two permissions it needs and run your first macro.
• Your first macroBuild a macro from scratch with When, Only if and Do, run it as a dry run and then for real, and read its trace.
• 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.
• 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.
• Variables and expressionsUse {{ }} templates, variables, operators and built-in functions to make a macro's steps depend on data.
• 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.
• 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.
• SnippetsType a short abbreviation and Switchboard replaces it with a longer text: fields to fill in, a caret position, the date, the clipboard.
• 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.
• 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.
• 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.
• 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.
• 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.
• Safari and ChromeConnect your browser to Switchboard, then start macros from pages, change pages, and let page buttons run macros and get the result.
• 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.
• 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.
• 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.
• 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.
• Make with AIDescribe a macro in a sentence and read what Claude wrote before anything is added or run.
• 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.
• 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.
• 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.
• 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.
• FunctionsShows how to make a macro that other macros call, with inputs and a result, and how to pull repeated steps out into one.
• 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.
• The InboxQuestions macros park instead of popping up a window, and where to answer them: the menu bar, the iPhone and the command line.
• Writing an extensionBuild a TypeScript extension that adds actions, conditions, triggers, functions or palette rows, and asks only for the permissions it needs.
• 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.
• Coming from Keyboard MaestroHow Keyboard Maestro's groups, triggers, actions, conditions, variables and tokens map to Switchboard, and how to import your library.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• Coming from HazelHow Hazel's folders, rules, conditions and actions map to Switchboard, and what the import keeps, notes or leaves out.
• Coming from TextExpander or AlfredImport snippets from TextExpander, Alfred, Raycast or macOS Text Replacements, and how their placeholders map to Switchboard's snippet tokens.
• 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.
• 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.
• Keyboard shortcutsEvery keyboard shortcut in Switchboard's menus and panels, and the key spec syntax used by Press keys and hotkey triggers.
• 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.
• Coming from RaycastHow Raycast's script commands, quicklinks, snippets and extensions map to Switchboard, and the hotkeys Raycast keeps encrypted.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• Dictation: hold to talkHold a key, speak, let go, and clean text lands where you were typing. On-device speech, an optional cleanup, a style per app.
• Paste asPress ⌃⌥V instead of ⌘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.

Reference