switchboard import

Details #

import has three forms. It picks the form from the file extension and flags.

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)

Keyboard Maestro. switchboard import file.kmmacros reads an exported file. switchboard import --km-library reads the macros of the Keyboard Maestro installation on this Mac.

switchboard import --km-library --dry
switchboard import ~/Desktop/Writing.kmmacros --take-over

BetterTouchTool. switchboard import file.bttpreset reads an exported preset. switchboard import --btt-library reads the BetterTouchTool library on this Mac.

switchboard import --btt-library --dry

LaunchBar. switchboard import --launchbar [path] reads an .lbaction bundle, a folder of them, or LaunchBar's own Actions folder. Each action becomes a macro with a palette keyword made from its name's initials; add --take-over to switch on the ones that can run. See the guide Coming from LaunchBar.

Hazel. switchboard import --hazel [file.hazelrules] reads a Hazel rules export (or the .hazelrules files in Hazel's own folder). Each watched folder becomes one macro with its rules as labelled if blocks; add --run-now to have each folder's macro catch up on what is already in it, and --take-over only after Hazel is paused on those folders. See the guide Coming from Hazel.

Karabiner-Elements. switchboard import --karabiner [karabiner.json] reads Karabiner's own file (or the one you name, or a rule file). Remaps, including dual-role keys, are sent to the engine switched off; layers and macros are saved with the groups. Quit Karabiner before you take over.

switchboard import --karabiner --dry

Automator and Shortcuts. switchboard import file.workflow reads one workflow. --automator reads the Quick Actions, workflows and folder actions in your Library, --shortcuts reads every shortcut in the Shortcuts app, and both flags together read both. Everything comes in enabled: neither app has hotkeys that would fire twice.

switchboard import --automator --shortcuts --dry

The Keyboard Maestro and BetterTouchTool importers save into the Library with a review. They print how many macros were imported, how many are enabled, need attention or are unsupported. The BetterTouchTool importer also reports key remaps, menu bar items and window actions that it recorded in the review but did not import.

Parameters #

switchboard import <file.switchboard> [--replace] add the groups and macros from an export

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. The Keyboard Maestro and BetterTouchTool forms reject it with exit 64.

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

• Imports run locally and do not need the engine.

See also #

• switchboard export

• switchboard lint