Automation

Use Settings → Automation to let another tool trigger a HyperSwitcher action. Choose what should happen and any options it needs, then copy either output:

• URL action for Shortcuts, Stream Deck, launchers, and other tools that can open a URL.
• Terminal command for shell scripts and command-line workflows.

Both outputs represent the same action and use HyperSwitcher’s normal app switching, window selection, Quick Layout, Workspace, profile, and shortcut behavior.

Create an action

1. Open Settings → Automation.
2. Choose an Action.
3. Choose the target or options shown for that action.
4. Copy the URL action or Terminal command from Generated output.
5. Paste it into your automation tool or script.

Focus app is the only action that asks you to select an app. Finder and profile actions each show their own target. Window actions, Workspace cycling, and temporary shortcuts deliberately leave the app unspecified. This lets one Shortcuts or Stream Deck action work with whichever external app or window is focused when you run it.

HyperSwitcher generates the correct URL encoding, stable identifiers where needed, URL scheme, and command name for you. The generator does not run the action.

Tip

Open an app in Settings → Apps when you only need to focus that app. Its Automation section has a ready-to-copy focus URL and Terminal command.

What you can automate

Every generated action is available as both a URL and Terminal command:

Action	What it does
Focus app	Launches or focuses an app, then follows the active profile’s normal app and window choices.
Focus Finder destination	Opens or focuses one of your saved Finder folder destinations. Targets are limited to saved destinations.
Switch profile	Activates a profile and reapplies its shortcuts and other profile-specific behavior.
Maximize or restore window	Uses HyperSwitcher’s gap-aware maximize or remembered restore frame for the focused external window.
Center window	Centers the focused external window without changing its size.
Resize window	Makes the focused external window larger or smaller by one or more steps from the current Quick Layout grid.
Place window	Places the focused external window by following an ordered Quick Layout recipe. Each step can select, combine, or resize the current region.
Cycle app windows	Moves to the next eligible window for the focused external app.
Window history	Moves Back or Forward through window focus history from the current app session.
Cycle Workspace windows	Uses the focused external window’s Workspace, with the normal pointer-display and current-Space fallback when no focused Workspace target is available.
Assign temporary shortcut	Gives the focused external app or exact focused window a temporary key, according to the selected Target.

These actions keep the same limits and settings as their keyboard equivalents. Window resizing uses the current grid and edge behavior, while placement uses Quick Layout gaps and animation. Temporary shortcuts still follow supported-key, conflict, license, and lifetime rules.

URL actions

URL actions are the simplest choice when the other tool can open a custom URL. For example:

hyperswitcher://app/focus?bundle-id=com.apple.Safari
hyperswitcher://finder/focus?target=Project%20Files
hyperswitcher://window/resize/larger?steps=3
hyperswitcher://window/place/right/larger/up/larger
hyperswitcher://window/history/back
hyperswitcher://workspace/cycle
hyperswitcher://shortcut/assign-temporary?target=window&key=S

Use the Settings generator instead of assembling these URLs by hand. It uses stable IDs for saved Finder destinations and profiles, and it percent-encodes spaces and other special characters correctly.

Focus the external app or window you want before opening a selector-free action. When HyperSwitcher is already running, it remembers the last externally focused window, so LaunchServices activating HyperSwitcher to deliver the URL does not replace the intended target.

Keep HyperSwitcher running when you open a URL action. A cold-launch URL has no warm target to preserve and is best effort; HyperSwitcher asks you to try the URL again if the action arrives before its command router is ready. A URL cannot return data to the tool that opened it, so HyperSwitcher reports malformed actions and other failures with a short in-app notice.

App focus always includes one explicit selector. When you intentionally want a window, Workspace, or temporary-shortcut action tied to a particular app, URL and CLI callers may also provide one of name, bundle-id, binding-id, or shortcut-key.

Install and use the command

The command is useful when a script needs a result. In Settings → Automation, find Command Line and click Install hyperswitcher. HyperSwitcher installs it at ~/.local/bin/hyperswitcher.

Restart Terminal, then check the connection to the running app:

hyperswitcher status

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

The generated Terminal form mirrors the URL action. These pairs perform the same action:

hyperswitcher://app/focus?bundle-id=com.apple.Safari
hyperswitcher focus --bundle-id 'com.apple.Safari'

hyperswitcher://window/resize/larger?steps=3
hyperswitcher window resize larger --steps 3

hyperswitcher://window/place/right/larger/up/larger
hyperswitcher window place right larger up larger

hyperswitcher://workspace/cycle
hyperswitcher workspace cycle

hyperswitcher://shortcut/assign-temporary?target=window&key=S
hyperswitcher shortcut assign-temporary --target window --key 'S'

These selector-free pairs are suitable for reusable Shortcuts or Stream Deck buttons because they follow the current external context. The same targeting rule applies when you write a CLI command yourself:

Command	Result
hyperswitcher window maximize	Maximizes the window using the current layout gaps and remembers its previous frame.
hyperswitcher window restore	Restores the frame remembered by HyperSwitcher.
hyperswitcher window center	Centers the window without changing its size.
hyperswitcher window resize larger	Resizes by one step using the current Quick Layout grid and edge behavior.
hyperswitcher window place right larger up larger	Places the window with an ordered Quick Layout recipe, adjusting each split before continuing.
hyperswitcher window cycle	Moves to the next eligible window for the focused app.
hyperswitcher window history back	Moves back through the current session’s window focus history. Use forward to retrace it.
hyperswitcher workspace cycle	Moves to the next available window in the current Workspace.
hyperswitcher shortcut assign-temporary --target window --key S	Assigns a temporary Hyper shortcut to the focused app or exact window.

Add one explicit selector when you intentionally want an app-specific action instead:

hyperswitcher window maximize --bundle-id com.apple.Safari
hyperswitcher workspace cycle --shortcut-key S
hyperswitcher shortcut assign-temporary --target app --key T --name Terminal

You can select an app by name, bundle ID, saved app binding, or assigned shortcut key. Use one selector at a time. Bundle IDs are usually the most stable choice for app-specific scripts.

For Place window, Settings → Automation shows one Placement recipe. The first step must be Left, Right, Up, or Down. Use Add step to continue the recipe. Later step menus also include Larger, Smaller, and the four Combine directions; there are no separate Adjustment or Steps rows for this action.

The CLI places the recipe steps after window place, while a URL puts the same steps in its path:

hyperswitcher window place <recipe-step>... [selector]
<scheme>://window/place/<recipe-step>/...

The available recipe steps are left, right, up, down, larger, smaller, combine-left, combine-right, combine-up, and combine-down. Each step runs in order. larger and smaller resize the split created or selected by the most recent directional placement step before the recipe continues, and you can repeat either adjustment.

For example:

hyperswitcher window place left left
hyperswitcher window place left left combine-right
hyperswitcher window place right larger up larger
hyperswitcher://window/place/right/larger/up/larger

The final CLI and URL examples place the window right, enlarge that split, place it up within the current region, then enlarge the new split. The separate Resize window action still uses a Larger or Smaller direction and a repeat count.

Read status and lists

The CLI also has read-only commands for scripts and troubleshooting:

Command	Result
hyperswitcher status	Shows the running app, Accessibility state, active profile, configured app count, and command connection.
hyperswitcher apps	Lists configured and running apps known to HyperSwitcher.
hyperswitcher apps --configured	Lists only app shortcuts in the active profile.
hyperswitcher finder	Lists saved Finder folder destinations in the active profile, including their IDs and local availability.
hyperswitcher profiles	Lists local profiles.
hyperswitcher profiles current	Shows the active profile.

These read-only and list operations are CLI-only. They do not appear in Settings → Automation and cannot be encoded as URL actions. Development builds also include regression commands for HyperSwitcher testing; those commands are not available as URL actions and do not ship in the normal app.

Results and exit status

Action and read-only commands require HyperSwitcher to be running. Human-readable output is the default; add --json when a script needs the structured response:

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

The command returns exit status 0 for success, 1 when HyperSwitcher rejects or cannot complete the request, and 2 when the local connection fails. Argument errors return another nonzero status before a request is sent.

Generate a URL from Terminal

You can also place url before a supported action command:

hyperswitcher url focus --bundle-id com.apple.Safari
hyperswitcher url finder focus "Project Files"
hyperswitcher url profiles use "Demo setup"
hyperswitcher url window place right larger up larger

This prints the correctly encoded URL for that copy of HyperSwitcher without contacting the running app or performing the action. Read-only, list, and regression commands are rejected because they have no URL equivalent.

Regular and development builds

The regular app uses hyperswitcher and hyperswitcher://. Development variants use matching names such as hyperswitcher-debug and hyperswitcher-debug://, so multiple builds do not compete for the same command or URL scheme. Settings → Automation always copies the right form for the app you are using.

The --bundle option can direct a CLI request to a particular running HyperSwitcher variant. Accessibility is still required for window control, and macOS may limit focusing windows on another Space or in full screen, as it does for normal HyperSwitcher controls.