Command-line control

The optional hyperswitcher command exposes common actions to Terminal, scripts, and hardware controllers. HyperSwitcher must be running.

Install the command

In Settings → Advanced, click Install hyperswitcher. Restart Terminal, then run:

hyperswitcher status

The command is installed at ~/.local/bin/hyperswitcher.

Note

If Terminal says command not found, add ~/.local/bin to your shell’s PATH, then open a new Terminal window.

Commands

Command	Result
hyperswitcher status	Shows the app version, Accessibility state, active profile, configured app count, and whether HyperSwitcher is running.
hyperswitcher apps	Lists configured and running apps known to HyperSwitcher.
hyperswitcher apps --configured	Lists only app shortcuts in the active profile, with their shortcut and running state.
hyperswitcher focus Safari	Launches or focuses an app by name.
hyperswitcher focus --bundle-id com.apple.Safari	Focuses by bundle identifier when the name could be ambiguous.
hyperswitcher profiles	Lists local profiles.
hyperswitcher profiles current	Shows the active profile.
hyperswitcher profiles use Work	Switches by profile ID, exact name, or an unambiguous part of the name.

Quote names that contain spaces:

hyperswitcher profiles use "Demo setup"

Add --json when another tool needs structured output:

hyperswitcher status --json
hyperswitcher apps --configured --json

How focus requests work

The command checks app shortcuts in the active profile, then running and installed apps. A focus request follows the same window selection, minimized-window, and pointer-display choices as the equivalent keyboard shortcut.

Accessibility is still required for window control, and macOS may limit focusing windows on another Space or in full screen.

The --bundle option can target a particular running app variant. Profile changes take effect immediately.