Package: ksc
kscA command line tool to document and describe keyboard shortcuts in a standardized and properly formatted way.The name of this program is a shorthand for (k)eyboard (s)hort(c)ut.Inspired by and adapted from Brett Terpstra'skbd plugin for Jekyll.Here's a few examples:$ ksc -ms -p command shift %
⇧+⌘+5
$ ksc -y command shift option control t
Hyper-T
$ ksc control +
Control-Shift-+
$ ksc ⌘⇧F
Shift-Command-FInstallationYou'll need Python 3. Install with pip:$ pip install kscSpecifying Keyboard ShortcutsThe simplest invocation of this program has some description of the keyboard shortcut
as the arguments. Many variations of input are accepted. Capitalization is not
important. You can use modifier key names and abbreviations, likeCommandandopt.
You can use modifier key symbols such as⇧and⌃. You can use the ASCII symbols
for modifiers that are used in theCocoa Text System Key
Bindings.Keys can be any letter or symbol on the keyboard. In addition, you can type the name
of a key, likeesc,return,home,pageup, andrightarrow,F5, andeject.
Most everything you try should just work. If it doesn't, open an issue and I'll add
it. Here's some examples:$ ksc command b
Command-B
$ ksc shift F2
Shift-F2
$ ksc fn f10
Fn-F10
$ ksc command-option-rightarrow
Option-Command-Right Arrow
$ ksc command shift %
Shift-Command-5
$ ksc $~r
Option-Shift-R
$ ksc ⇧⌘P
Shift-Command-PSequences of multiple keyboard shortcuts can be entered by separating them with a/or|(the spaces surrounding the slash or the pipe are required).$ ksc control x / control c
Control-X Control-CIf you have a sequence of multiple keyboard shortcuts and the first one has a slash,
you can clarify the shortcut by joining the elements of the shortcut with a-:$ ksc command-/ / control-f
Command-/ Control-FIn addition to friendly modifier names, you can also enter keyboard shortcuts using
unicode symbols or ASCII symbols representing the modifiers. The ASCII symbols are
the same as those used by Apple in theCocoa Text System Key Bindings.ModifierUnicodeASCIIControl⌃^Option⌥~Shift⇧$Command⌘@Getting HelpYou are currently reading the help for this program. You can see a brief summary by
using the help command line option:$ ksc -hCustomizing OutputThe output is standardized according to Apple's Style Guidelines (see
below), including names of modifiers, keys, capitalization, interpretation of shifted
symbols and characters, and sequence of modifiers if there are more than one.There are several command line options to modify the output. The-msor--modifier-symbolsoptions output the modifers as unicode symbols:$ ksc -ms shift command u
⇧⌘UApple says you should include a plus sign between symbols, but I think that it looks
ugly, so that's not the default. If you want it, add the-por--plus-signwhen
using-ms:$ ksc -ms -p shift command u
⇧+⌘+UYou can also have the modifier symbols output as their ASCII representation by using
the-maor--modifier-asciioptions:$ ksc -ma shift command u
$@UThe-kor--key-symbolsargument causes all keys to be output as their symbol,
instead of their name. Makes most sense when used with-ms:$ ksc -ms -k control option pageup
⌃⌥⇞The-cor--clarify-keysoutputs some less-readable keys as names and symbols,
instead of just symbols. This setting is ignored if you use-k. Here's you can see
the difference when you use-c:$ ksc command .
Command-.
$ ksc -c command .
Command-Period (.)Show Me The KeysThe alpha-numeric keys likeTand8are easily known and understood. However, you may
not know all the names and symbols for the other keys. You can get a list with:$ ksc -lKeyboard MaestroI have created a simpleKeyboard Maestromacro
which allows you to usekscanywhere you can type on your Mac. I set a typed input trigger
so when I type;ksc, Keyboard Maestro prompts me for input. I type in the keyboard shortcut
I want, and Keyboard Maestro runs the script, captures the output, and then types the output
where my cursor is.Download theKeyboard Shortcut macrofor Keyboard Maestro.AlfredIf you useAlfred, there is aKeyboard Shortcut workflowwhich uses
the command line program. The workflow includes a snippet trigger ofksc.
If your snippet prefix is//, then you can type//kscand Alfred will
prompt you for input, where you can type the text representation of a keyboard
shortcut. Alfred will paste the standardized version at the location of the cursor.Download theKeyboard Shortcut workflowfor Alfred.The Hyper KeyUsingKarabiner ElementsorBetterTouchTool, you can makeCaps Lock-Tbe the same as
pressingControl-Option-Shift-Command-T. Mac nerds call this theHyper
key. You can always
usehyperas a modifier key when entering a keyboard shortcut:$ ksc hyper-t
Control-Option-Shift-Command-TIf you give the-yor--hypercommand line option, you will get aHyperkey in
your output when it's appropriate:$ ksc -y control option shift command t
Hyper-T
# ksc -y hyper t
Hyper-TTips and TricksYou can easily get the unicode symbol for a key and put it on your clipboard (on MacOS) with:$ ksc -k home | pbcopyBecause the tilde character~can mean both theOptionkey as well asShift-Grave, the
following input is ambiguous:$ ksc '$@~'Note the single quotes to protect all those special characters from being
interpreted by your shell. This could either meanShift-Command-~, which is valid,
orShift-Command-Option, which is not, therefore this input causes a parsing
error. You can clarify by using:$ ksc command tilde
Shift-Command-~or:$ ksc -c shift command grave
Shift-Command-Tilde (~)Apple StyleThis program implements the rules given inApple's Style Guideunder definition "key, keys". Their deep links are not semantic and seem liable to change, so you'll
just have to search for it.If you strictly followed the Style Guide, the keyboard shortcut to take a screenshot
would be Command-Shift-%. However, Apple never refers to it this way, they use
Command-Shift-5. SeeTake screenshots or screen recordings on Mac.
It appears the unwritten rule is that if the keyboard shortcut includes one of the
number keys and shift, instead of showing the symbol you show the number.Apple'sHuman Interface Guidelinesconflict with the style guide:For example, the keyboard shortcut for Help is
Command-Question mark (?), not Shift-Command-Slash.According to the style guide, it should be Command-Shift-Question markThis program implements the style guide plus the unwritten rule, and ignores the conflict in the HIG.