Browse the docs

switchboard ext

Lists, installs, removes, enables and disables extensions, prints their logs, starts one from a template, checks one, and develops one live from a folder.

Details #

switchboard ext list [--json]
switchboard ext install <folder|gallery id> [--yes] [--dev]
switchboard ext remove <id>
switchboard ext enable <id>
switchboard ext disable <id>
switchboard ext logs <id> [--follow]
switchboard ext dev <folder>
switchboard ext new <folder> [--from <template>] [--kinds action,trigger] [--prefix com.you]
switchboard ext check <folder> [--json]
switchboard ext intent <extension id> <intent id> [--param value …]

dev loads the folder into the running engine as a development copy (no signature needed), watches it, runs tsc on every save, hot-reloads the extension and streams its log. A build or manifest error is printed and the previous version keeps running. A folder with Package.swift and manifest.json is built with swift build into an ad hoc signed .sbext instead. Press ⌃C to stop.

install shows the permissions the extension asks for, and installs after you approve them (--yes approves without asking). A gallery id installs the gallery's signed build. An unsigned folder installs only with --dev.

new writes a starter extension with no model and no engine: switchboard.json, package.json, tsconfig.json, src/index.ts, a README with a Permissions section, a CHANGELOG, a test, and the SDK's types, so it compiles with the compiler inside Switchboard. --from names a template (hello, action-pack, trigger-source, sensor, menu-bar-item, importer); --kinds picks the template that fits what you want to add. A bare name goes in the Develop folder (~/Switchboard-Extensions, Settings › Develop) and gets the id prefix set there; a path is used as given. It never writes over an existing folder.

check runs the whole check pass without installing: the manifest, the TypeScript compile, the gallery's rules (permissions against the code, banned APIs) and the folder's own tests in the real Runtime. It prints one line per problem and exits 1 when there is any; --json prints the report. Make an extension, the check_extension tool and this command are the same pass.

logs prints what the extension logged, also after it crashed or was removed; --follow keeps printing.

intent runs an intent an extension exposes, for a Shortcut's Run Shell Script action.

[dev] watching /Users/you/Switchboard-Extensions/hello (Ctrl-C to stop)
[dev] built
[dev] reloaded com.yourname.hello (1 methods)

Parameters #

switchboard ext list [--json]
switchboard ext install <folder|gallery id> [--yes] [--dev] install one (shows the permissions it asks for; --yes approves them)
switchboard ext remove <id>
switchboard ext enable <id> | ext disable <id>
switchboard ext logs <id> [--follow]
switchboard ext dev <folder>
switchboard ext new <folder> [--from template] [--kinds a,b] [--prefix com.you] a starter extension in a new folder (a bare name goes in the Develop folder)
switchboard ext check <folder> [--json]
switchboard ext intent <extension id> <intent id> [--param value]… run an extension's Shortcuts action (what a Run Shell Script step calls)

The installed extensions.

Remove one (Undo from the Extensions window).

The extension's log.

Develop an extension: rebuild, hot-reload and stream its log.

Check an extension: manifest, compile, rules and tests; exit 1 on problems.

Gotchas #

  • The engine must be running for every subcommand except new and check.

See also #