switchboard import

Details #

import brings macros into the Library from a Switchboard export or from another app.

A Switchboard export. switchboard import file.switchboard unpacks the archive, lints it and adds its groups and macros to the Library. If the lint finds errors, nothing is imported and the errors are printed.

switchboard import ~/Desktop/backup.switchboard

The command waits (up to 20 seconds) until the engine has loaded the macros it added, so switchboard import file && switchboard run "…" works. If the engine is not running it returns at once; the macros load when it starts. A file that isn't an export, or that has problems, is refused with one message that names the file in the archive, not a folder on this Mac; set SWITCHBOARD_VERBOSE=1 for the technical detail.

imported: 1 new groups, 12 macros added, 0 replaced, 3 skipped (same id; use --replace)

Parameters #

switchboard import <file.switchboard> [--replace] add the groups and macros from an export
switchboard import [list] [--json]
switchboard import <app|file> [--take-over] [--dry-run] bring in an app's library (km, btt, karabiner, alfred, raycast, launchbar, hazel, automator,
switchboard import --hand-over [--dry-run] <app>
switchboard import --put-back <app>

The apps Switchboard can import from, and where each stands.

Also quit the app, stop its login launch and turn the macros on.

Undo a hand-over: macros off, the app back.

Examples #

# see what a Keyboard Maestro file would turn into, save nothing
switchboard import Writing.kmmacros --dry | jq '.'

Gotchas #

• --replace is only for .switchboard files.

• Usage mistakes in the importer forms exit with 64; unreadable files exit with 65.

• Imports run locally and do not need the engine.

One command for every app #

switchboard import reads one list of apps, so every app is imported the same way. Name an app and Switchboard reads its own data on this Mac; name a file and it works out which app made it.

switchboard import                         # what is on this Mac, app by app
switchboard import km --dry-run            # the review as JSON, nothing saved
switchboard import btt
switchboard import ~/Desktop/Writing.kmmacros --take-over

switchboard import (or import list) prints one line per app: its state (found, installed with nothing to bring, brought in, handed over, running again, failed), whether it is running, whether it starts at login, and what it holds. --json prints the same as JSON.

The names are km, btt, karabiner, alfred, raycast, launchbar, hazel, automator, shortcuts, popclip, textexpander and replacements (Text Replacements). The long forms (keyboard-maestro, bettertouchtool) work too. Apps that keep nothing Switchboard can read on this Mac (PopClip, Raycast, TextExpander) take a file: switchboard import raycast ~/scripts, switchboard import popclip Say.popclipext.

Old spellings still work. --km-library, --btt-library [--path <store>], --karabiner [file], --hazel [file] [--run-now], --launchbar [path], --alfred [path], --raycast <path>, --popclip <file>, --automator [file], --shortcuts (both flags together read Automator and Shortcuts) and --dry are aliases for the forms above. --run-now makes each Hazel folder's macro catch up on what is already in the folder.

Each app's library, and the files it exports, are in its guide: Coming from Keyboard Maestro, BetterTouchTool, Karabiner-Elements, Hazel, LaunchBar, Automator and Shortcuts.

Handing an app over #

Two apps acting on one hotkey is why imported macros come in switched off while the other app runs. --hand-over does the whole switch for one app: it brings the app in with its macros off, quits the app, stops it starting at login where Switchboard can, and then turns the macros on.

switchboard import --hand-over --dry-run karabiner   # the steps, nothing changed
switchboard import km --hand-over
switchboard import --put-back km

Switchboard never edits another app's settings. A login item that only the app (or System Settings) can change is reported as "needs you" and System Settings opens at Login Items so you can turn it off; a Karabiner LaunchAgent is stopped for this login session with launchctl and started again by Put Back. What is left to you is printed.

--put-back undoes it and nothing more: the app's macros are turned off (they stay in the Library), the login launch comes back if Switchboard stopped it, and the app opens again if it was running before. What was done is kept in switch-overs.json in the support folder; it holds no data from the other app. --switch-over and --restore are older spellings of --hand-over and --put-back.

The engine serves the scan and the hand-over for the app: GET /import/scan, POST /import/switch-over and POST /import/put-back. They never import a file.

Whatever app it reads, the importer saves into the Library with a review and prints how many macros came in, how many are enabled, need attention or are unsupported. BetterTouchTool and Karabiner send their key remaps to the engine, switched off, and report what they recorded in the review but did not import.

See also #

• switchboard export

• switchboard lint