Skip to content

Latest commit

 

History

History
134 lines (99 loc) · 7.3 KB

README.md

File metadata and controls

134 lines (99 loc) · 7.3 KB
Raw

Anykey App Icon

Anykey

Disclaimer: Anykey is free, open-source software. I maintain it in my spare time. Use at your own risk.

A free macOS app for binding shell commands to system-wide or app-specific hotkeys. It’s configured via a text file that can be stored in Git or synced to Dropbox.

Screenshot

For the curious: Read the story behind Anykey on my personal blog.

Who is it for?

Primarily, macOS automation enthusiasts like myself who wish to store their hotkey configuration in Git or generate it programmatically. All existing alternatives (that I’m aware of) make this impossible or very difficult. Karabiner-Elements comes pretty close though (here’s an example config).

App Text config App-specific hotkeys Auto-reload Free Open Source
⌘ Anykey ✅ ✅ ✅ ✅ ✅
Automator + System preferences ❌ ✅ ❌ ✅ ❌
Alfred Powerpack ❌ ✅ ❌ ❌ ❌
Karabiner-Elements ✅ ✅ ❌ ✅ ✅
Keyboard Maestro ❌ ✅ ❌ ❌ ❌
Hammerspoon ✅ ❌ ❌ ✅ ✅

Installation

Requires macOS 10.15 Catalina or later, optimized for macOS 11 Big Sur. Runs natively on both Intel and Apple Silicon Macs.

  • Download the latest release from GitHub.
  • Unzip and copy the app to your Applications folder.
  • Launch the app (which macOS will refuse, because I’m not a “verified developer”).
  • Go to “Security & Privacy 〉General” in System Preferences and manually allow the blocked app.
  • Launch Anykey again. It’ll ask for Accessibility permissions, follow the link in the prompt to enable.
  • Launch Anykey one more time, then press ⌘+⌥+⌃+⇧+A. You should hear a greeting (make sure your sound is on). If you enabled notifications, you should see a notification banner pop up.

Launching on startup

To launch Anykey on startup, add it to your login items (System Preferences 〉Users & Groups 〉Login Items).

Hiding the status bar icon

If you would rather not have Anykey in your status bar, there’s an option to "Hide Anykey from status bar" in Settings. When Anykey is hidden, launch it again to show settings, press the “Quit” button in settings to quit.

Configuration

By default, Anykey will create a JSON config at ~/.Anykey.json if it’s missing. This path can be changed in app preferences. Anykey auto-reloads its configuration whenever the specified file changes on the disk, reporting any errors via macOS notifications.

{
    "hotkeys":
    [ { "title": "Anykey welcome"
      , "displayNotification": true
      , "key": "a"
      , "modifiers": ["⌘", "⇧", "⌥", "⌃"]
      , "shellCommand": "say 'Thank you for using Anykey!'"
      }
    ]
}

Recognized top-level (global) settings are:

  • hotkeys (required) - an array of hotkey definitions (see below)
  • workingDirectory (optional) - a string path to the directory at which to run shell commands (unless overridden per hotkey), defaults to "/".

The hotkey definition supports the following attributes:

  • title (required) - a concise description of what the hotkey does. It will be used in triggered notifications;
  • key (required) - a string describing the symbol part of the desired hotkey (e.g., o in ⌘+o);
  • modifiers (required) — a string array of one or more modifiers (see below) that need to be held for the key to trigger the command;
  • shellCommand (required) - a string describing the shell command to run when the hotkey is pressed;
  • onlyIn (optional) - a string array of bundle IDs of apps that this hotkey should only be triggered in.
  • displayNotification (optional) - a boolean flag determining whether to show a banner notification whenever this command runs, default false.
  • workingDirectory (optional) - a string path to the directory at which to run the specified shell command, defaults to "/", takes precedence over the global setting.

Here’s a handy command for getting a bundle ID value for any given app:

mdls -name kMDItemCFBundleIdentifier -r /Applications/Anykey.app

Supported modifiers and their identifiers

  • ⌘ (Command): "cmd", "command", "⌘";
  • ⌥ (Option): "alt", "option", "opt", "⌥";
  • ⇧ (Shift): "shift", "⇧";
  • ⌃ (Control): "control", "ctrl", "^";
  • fn (Function): "function", "fn".

Example hotkeys

Launch an app. E.g., ⌥+⇧+` to launch iTerm2:

{
    "hotkeys":
        [ { "title": "Launch iTerm 2"
          , "key": "`"
          , "modifiers": ["option", "shift"]
          , "shellCommand": "open /Applications/iTerm.app",
          }
        ]
}

Run an AppleScript. E.g., press ⌥+⇧+= to enter "AWS jokes" in Alfred 2:

{
    "hotkeys":
        [ { "title": "Search foo in Alfred"
          , "key": "="
          , "modifiers": ["alt", "shift"]
          , "shellCommand": "osascript -e tell application \"Alfred 4\" to search \"AWS jokes\"",
          }
        ]
}

Note: For any non-trivial scripts, consider storing them in separate files (which makes them easier to edit and debug), then run via osascript filename.scpt (optionally, use the global workingDirectory option to avoid repeating long file paths).

Acknowledgments