Shorty

Manage macOS menu keyboard shortcuts — the ones in System Settings → Keyboard → Keyboard Shortcuts → App Shortcuts — from one YAML file.

Status: not yet released. There is no download and no install command yet. Release news will be posted on the blog, which has an Atom feed.

What it is

Shorty.app is a menu bar app with an editor for the file. It syncs again whenever the file changes.
shorty is a command line tool that does everything the app does.

Shorty only ever touches shortcuts it created, or that you declared in the file. Shortcuts you made by hand stay exactly as they are.

What it does

Picks titles from real menus. Menu titles are picked from the app’s real menus rather than typed, and existing titles are checked against them. A New Tab where Chrome says New tab, a missing …, or an item the developer renamed is caught and fixed in one click.
Groups. Organise shortcuts into groups you switch on and off together.
Import. Bring in the shortcuts you already have, at any time.
Apps that are not installed yet. Shortcuts for apps that are not installed are held until the app shows up.
One file. Keep the shortcuts in Shorty’s own folder, or in a YAML file you choose, such as one in a dotfiles repo.

The file

Shortcuts are written as modifier+…+key. Modifiers are cmd, opt (or alt), ctrl and shift. Menu titles must match the menu item exactly, and -> separates a submenu path.

yaml

version: 1

global:                                # every app that has a matching menu item
  "System Settings...": cmd+shift+,

apps:
  com.google.Chrome:                   # bundle identifier
    "Pin Tab": cmd+p
    "New Tab Below": cmd+opt+t
  com.apple.TextEdit:
    "Format->Font->Ligatures->Use Default": cmd+opt+ctrl+l    # submenu path

groups:
  writing:
    description: Only while drafting
    enabled: false                     # optional, default true
    apps:
      com.apple.TextEdit:
        "Format->Font->Bigger": cmd++

What is in effect is the ungrouped entries plus every enabled group. Disabling a group removes its shortcuts from the Mac on the next sync.

Shorty owns the file. The editor and some commands rewrite it in a canonical form, so comments and ordering in a hand-edited file do not survive the next write. Before overwriting, Shorty copies the file to a backups/ folder beside it (the newest 20 are kept), and the editor can restore one.

The command line

Command	What it does
`shorty sync [--dry-run] [--restart]`	Make this Mac match the file
`shorty status`	Pending changes, plus managed and unmanaged counts
`shorty validate`	Check the config only; exit code 2 if invalid
`shorty list [--all]`	Managed shortcuts; --all includes hand-made ones
`shorty import [<bundle-id>…] [--write]`	Print the shortcuts already on this Mac; --write adds the undeclared ones to the file
`shorty menus <bundle-id> [--search <text>]`	An app’s real menu titles, with their current shortcuts
`shorty check [<bundle-id>…] [--fix]`	Find titles that do not match a real menu item, and key combinations that cannot work
`shorty reserved`	The key combinations macOS itself already uses
`shorty group enable\|disable <name>…`	Switch groups on and off (then syncs)
`shorty clear [<bundle-id>…] [--yes]`	Remove managed shortcuts (never unmanaged ones)
`shorty init`	Create a commented starter config

Every command takes --config <path>, --json, --quiet and --verbose. Exit codes: 0 ok, 1 failure (including a partly applied sync), 2 invalid config.

Permissions

macOS asks for permission when Shorty needs it, once per thing you just did:

Adding, importing or enabling a sandboxed app (Mail, Notes, TextEdit, most App Store apps) asks to access data from other apps, for that one app. If you decline, that app is marked Needs permission and skipped, and everything else keeps syncing.
The menu picker and title checking need Accessibility, asked once. Without it, everything else works and you type titles by hand.

Apps read their shortcuts at launch, so restart an app to see changes.

Requirements

macOS 15 (Sequoia) or later.

Status

Shorty has not been released. When it is, this page will say where to download it and the blog will carry the news. Follow the Atom feed to hear about it.