| Name | ksc JSON |
| Version |
1.4
JSON |
| download |
| home_page | None |
| Summary | A command line tool and python library for documenting and describing keyboard shortcuts. |
| upload_time | 2025-10-13 18:46:47 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
keyboard shortcut
documentation
command line
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ksc
A 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's
[kbd plugin for Jekyll](https://github.com/ttscoff/JekyllPlugins/tree/master/KBDTag).
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-F
$ ksc -y hyper space
Hyper-Space
## Installation
You'll need Python 3. Install with [pipx](https://github.com/pypa/pipx):
$ pipx install ksc
or [uv](https://docs.astral.sh/uv/guides/tools/#installing-tools):
$ uv tool install ksc
## Specifying Keyboard Shortcuts
The 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, like `Command` and `opt`.
You can use modifier key symbols such as `⇧` and `⌃`. You can use the ASCII symbols
for modifiers that are used in the [Cocoa Text System Key
Bindings](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/EventOverview/TextDefaultsBindings/TextDefaultsBindings.html).
Keys can be any letter or symbol on the keyboard. In addition, you can type the name
of a key, like `esc`, `return`, `home`, `pageup`, and `rightarrow`, `F5`, and `eject`.
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-P
Sequences 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-C
If 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-F
In 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 the
[Cocoa Text System Key Bindings](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/EventOverview/TextDefaultsBindings/TextDefaultsBindings.html).
| Modifier | Unicode | ASCII |
|------------|:-------:|:-----:|
| Control | `⌃` | `^` |
| Option | `⌥` | `~` |
| Shift | `⇧` | `$` |
| Command | `⌘` | `@` |
Apple uses the Globe key as a modifier, but doesn't document an ASCII representation
for it. When they display it in their documentation, they use the word "Globe" or an
image, not the globe with meridians unicode symbol that seems like the closest match.
Because this tool is text based, we use "Globe" if you ask for the Unicode or ASCII
representation of that key.
## Getting Help
You are currently reading the help for this program. You can see a brief summary by
using the help command line option:
$ ksc -h
## Customizing Output
The 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 `-ms` or
`--modifier-symbols` options output the modifers as unicode symbols:
$ ksc -ms shift command u
⇧⌘U
Apple 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 `-p` or `--plus-sign` when
using `-ms`:
$ ksc -ms -p shift command u
⇧+⌘+U
You can also have the modifier symbols output as their ASCII representation by using
the `-ma` or `--modifier-ascii` options:
$ ksc -ma shift command u
$@U
The `-k` or `--key-symbols` argument 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 `-c` or `--clarify-keys` outputs 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 Keys
The alpha-numeric keys like `T` and `8` are 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 -l
## Keyboard Maestro
I have created a simple [Keyboard Maestro](https://www.keyboardmaestro.com/) macro
which allows you to use `ksc` anywhere 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.
[](https://github.com/kotfu/ksc/releases/latest)
Download the [Keyboard Shortcut macro](https://github.com/kotfu/ksc/releases/latest) for Keyboard Maestro.
## Alfred
If you use [Alfred](https://www.alfredapp.com/), there is a
[Keyboard Shortcut workflow](https://github.com/kotfu/ksc/releases/latest) which uses
the command line program. The workflow includes a snippet trigger of `ksc`.
If your snippet prefix is `//`, then you can type `//ksc` and 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 the [Keyboard Shortcut workflow](https://github.com/kotfu/ksc/releases/latest) for Alfred.
## The Hyper Key
Using [Karabiner Elements](https://karabiner-elements.pqrs.org/) or
[BetterTouchTool](https://folivora.ai/), you can make `Caps Lock-T` be the same as
pressing `Control-Option-Shift-Command-T`. Mac nerds call this the [Hyper
key](https://statusq.org/archives/2016/09/25/7857/). You can always
use `hyper` as a modifier key when entering a keyboard shortcut:
$ ksc hyper-t
Control-Option-Shift-Command-T
If you give the `-y` or `--hyper` command line option, you will get a `Hyper` key in
your output when it's appropriate:
$ ksc -y control option shift command t
Hyper-T
# ksc -y hyper t
Hyper-T
## Tips and Tricks
* You can easily get the unicode symbol for a key and put it on your clipboard (on MacOS) with:
$ ksc -k home | pbcopy
* Because the tilde character `~` can mean both the `Option` key as well as `Shift-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 mean `Shift-Command-~`, which is valid,
or `Shift-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 Style
This program implements the rules given in [Apple's Style Guide](https://help.apple.com/applestyleguide)
under 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. See
[Take screenshots or screen recordings on Mac](https://support.apple.com/guide/mac-help/take-a-screenshot-or-screen-recording-mh26782/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's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/macos/user-interaction/keyboard/)
conflict 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 mark
This program implements the style guide plus the unwritten rule, and ignores the conflict in the HIG.
Raw data
{
"_id": null,
"home_page": null,
"name": "ksc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "keyboard shortcut, documentation, command line",
"author": null,
"author_email": "Jared Crapo <jared@kotfu.net>",
"download_url": "https://files.pythonhosted.org/packages/cd/70/25179a17a2ddc6373234a46471740e3b814252f4c1d51a74b4bbb9fb268b/ksc-1.4.tar.gz",
"platform": null,
"description": "# ksc\n\nA command line tool to document and describe keyboard shortcuts in a standardized and properly formatted way.\n\nThe name of this program is a shorthand for (k)eyboard (s)hort(c)ut.\n\nInspired by and adapted from Brett Terpstra's\n[kbd plugin for Jekyll](https://github.com/ttscoff/JekyllPlugins/tree/master/KBDTag).\n\nHere's a few examples:\n\n $ ksc -ms -p command shift %\n \u21e7+\u2318+5\n $ ksc -y command shift option control t\n Hyper-T\n $ ksc control +\n Control-Shift-+\n $ ksc \u2318\u21e7F\n Shift-Command-F\n $ ksc -y hyper space\n Hyper-Space\n\n\n## Installation\n\nYou'll need Python 3. Install with [pipx](https://github.com/pypa/pipx):\n\n $ pipx install ksc\n\nor [uv](https://docs.astral.sh/uv/guides/tools/#installing-tools):\n\n $ uv tool install ksc\n\n\n## Specifying Keyboard Shortcuts\n\nThe simplest invocation of this program has some description of the keyboard shortcut\nas the arguments. Many variations of input are accepted. Capitalization is not\nimportant. You can use modifier key names and abbreviations, like `Command` and `opt`.\nYou can use modifier key symbols such as `\u21e7` and `\u2303`. You can use the ASCII symbols\nfor modifiers that are used in the [Cocoa Text System Key\nBindings](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/EventOverview/TextDefaultsBindings/TextDefaultsBindings.html).\n\nKeys can be any letter or symbol on the keyboard. In addition, you can type the name\nof a key, like `esc`, `return`, `home`, `pageup`, and `rightarrow`, `F5`, and `eject`.\nMost everything you try should just work. If it doesn't, open an issue and I'll add\nit. Here's some examples:\n\n $ ksc command b\n Command-B\n $ ksc shift F2\n Shift-F2\n $ ksc fn f10\n Fn-F10\n $ ksc command-option-rightarrow\n Option-Command-Right Arrow\n $ ksc command shift %\n Shift-Command-5\n $ ksc $~r\n Option-Shift-R\n $ ksc \u21e7\u2318P\n Shift-Command-P\n\n\nSequences of multiple keyboard shortcuts can be entered by separating them with a ` / `\nor ` | ` (the spaces surrounding the slash or the pipe are required).\n\n $ ksc control x / control c\n Control-X Control-C\n\nIf you have a sequence of multiple keyboard shortcuts and the first one has a slash,\nyou can clarify the shortcut by joining the elements of the shortcut with a `-`:\n\n $ ksc command-/ / control-f\n Command-/ Control-F\n\nIn addition to friendly modifier names, you can also enter keyboard shortcuts using\nunicode symbols or ASCII symbols representing the modifiers. The ASCII symbols are\nthe same as those used by Apple in the\n[Cocoa Text System Key Bindings](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/EventOverview/TextDefaultsBindings/TextDefaultsBindings.html).\n\n| Modifier | Unicode | ASCII |\n|------------|:-------:|:-----:|\n| Control | `\u2303` | `^` |\n| Option | `\u2325` | `~` |\n| Shift | `\u21e7` | `$` |\n| Command | `\u2318` | `@` |\n\nApple uses the Globe key as a modifier, but doesn't document an ASCII representation\nfor it. When they display it in their documentation, they use the word \"Globe\" or an\nimage, not the globe with meridians unicode symbol that seems like the closest match.\nBecause this tool is text based, we use \"Globe\" if you ask for the Unicode or ASCII\nrepresentation of that key.\n\n\n## Getting Help\n\nYou are currently reading the help for this program. You can see a brief summary by\nusing the help command line option:\n\n $ ksc -h\n\n\n## Customizing Output\n\nThe output is standardized according to Apple's Style Guidelines (see\nbelow), including names of modifiers, keys, capitalization, interpretation of shifted\nsymbols and characters, and sequence of modifiers if there are more than one.\n\nThere are several command line options to modify the output. The `-ms` or\n`--modifier-symbols` options output the modifers as unicode symbols:\n\n $ ksc -ms shift command u\n \u21e7\u2318U\n\nApple says you should include a plus sign between symbols, but I think that it looks\nugly, so that's not the default. If you want it, add the `-p` or `--plus-sign` when\nusing `-ms`:\n\n $ ksc -ms -p shift command u\n \u21e7+\u2318+U\n\nYou can also have the modifier symbols output as their ASCII representation by using\nthe `-ma` or `--modifier-ascii` options:\n\n $ ksc -ma shift command u\n $@U\n\nThe `-k` or `--key-symbols` argument causes all keys to be output as their symbol,\ninstead of their name. Makes most sense when used with `-ms`:\n\n $ ksc -ms -k control option pageup\n \u2303\u2325\u21de\n\nThe `-c` or `--clarify-keys` outputs some less-readable keys as names and symbols,\ninstead of just symbols. This setting is ignored if you use `-k`. Here's you can see\nthe difference when you use `-c`:\n\n $ ksc command .\n Command-.\n $ ksc -c command .\n Command-Period (.)\n\n\n## Show Me The Keys\n\nThe alpha-numeric keys like `T` and `8` are easily known and understood. However, you may\nnot know all the names and symbols for the other keys. You can get a list with:\n\n $ ksc -l\n\n\n## Keyboard Maestro\n\nI have created a simple [Keyboard Maestro](https://www.keyboardmaestro.com/) macro\nwhich allows you to use `ksc` anywhere you can type on your Mac. I set a typed input trigger\nso when I type `;ksc`, Keyboard Maestro prompts me for input. I type in the keyboard shortcut\nI want, and Keyboard Maestro runs the script, captures the output, and then types the output\nwhere my cursor is.\n\n[](https://github.com/kotfu/ksc/releases/latest)\n\nDownload the [Keyboard Shortcut macro](https://github.com/kotfu/ksc/releases/latest) for Keyboard Maestro.\n\n\n## Alfred\n\nIf you use [Alfred](https://www.alfredapp.com/), there is a\n[Keyboard Shortcut workflow](https://github.com/kotfu/ksc/releases/latest) which uses\nthe command line program. The workflow includes a snippet trigger of `ksc`.\nIf your snippet prefix is `//`, then you can type `//ksc` and Alfred will\nprompt you for input, where you can type the text representation of a keyboard\nshortcut. Alfred will paste the standardized version at the location of the cursor.\n\nDownload the [Keyboard Shortcut workflow](https://github.com/kotfu/ksc/releases/latest) for Alfred.\n\n\n## The Hyper Key\n\nUsing [Karabiner Elements](https://karabiner-elements.pqrs.org/) or\n[BetterTouchTool](https://folivora.ai/), you can make `Caps Lock-T` be the same as\npressing `Control-Option-Shift-Command-T`. Mac nerds call this the [Hyper\nkey](https://statusq.org/archives/2016/09/25/7857/). You can always\nuse `hyper` as a modifier key when entering a keyboard shortcut:\n\n $ ksc hyper-t\n Control-Option-Shift-Command-T\n\nIf you give the `-y` or `--hyper` command line option, you will get a `Hyper` key in\nyour output when it's appropriate:\n\n $ ksc -y control option shift command t\n Hyper-T\n # ksc -y hyper t\n Hyper-T\n\n\n## Tips and Tricks\n\n* You can easily get the unicode symbol for a key and put it on your clipboard (on MacOS) with:\n\n $ ksc -k home | pbcopy\n\n* Because the tilde character `~` can mean both the `Option` key as well as `Shift-Grave`, the\n following input is ambiguous:\n\n $ ksc '$@~'\n\n Note the single quotes to protect all those special characters from being\n interpreted by your shell. This could either mean `Shift-Command-~`, which is valid,\n or `Shift-Command-Option`, which is not, therefore this input causes a parsing\n error. You can clarify by using:\n\n $ ksc command tilde\n Shift-Command-~\n\n or:\n\n $ ksc -c shift command grave\n Shift-Command-Tilde (~)\n\n\n## Apple Style\n\nThis program implements the rules given in [Apple's Style Guide](https://help.apple.com/applestyleguide)\nunder definition \"key, keys\". Their deep links are not semantic and seem liable to change, so you'll\njust have to search for it.\n\nIf you strictly followed the Style Guide, the keyboard shortcut to take a screenshot\nwould be Command-Shift-%. However, Apple never refers to it this way, they use\nCommand-Shift-5. See\n[Take screenshots or screen recordings on Mac](https://support.apple.com/guide/mac-help/take-a-screenshot-or-screen-recording-mh26782/mac).\nIt appears the unwritten rule is that if the keyboard shortcut includes one of the\nnumber keys and shift, instead of showing the symbol you show the number.\n\nApple's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/macos/user-interaction/keyboard/)\nconflict with the style guide:\n\n> For example, the keyboard shortcut for Help is\n> Command-Question mark (?), not Shift-Command-Slash.\n\nAccording to the style guide, it should be Command-Shift-Question mark\n\nThis program implements the style guide plus the unwritten rule, and ignores the conflict in the HIG.\n",
"bugtrack_url": null,
"license": null,
"summary": "A command line tool and python library for documenting and describing keyboard shortcuts.",
"version": "1.4",
"project_urls": {
"homepage": "https://github.com/kotfu/ksc"
},
"split_keywords": [
"keyboard shortcut",
" documentation",
" command line"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "152efce71427fa4b12b3d4f603ade9bbdc891005614f5652785c18f907913dea",
"md5": "e0322a28a23919b75f901ef4eae4fdaa",
"sha256": "eb3bd8b2941cffb537a23de15b73e952a04eae22a60c3b262155e96a19f1b0ff"
},
"downloads": -1,
"filename": "ksc-1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0322a28a23919b75f901ef4eae4fdaa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15052,
"upload_time": "2025-10-13T18:46:46",
"upload_time_iso_8601": "2025-10-13T18:46:46.221560Z",
"url": "https://files.pythonhosted.org/packages/15/2e/fce71427fa4b12b3d4f603ade9bbdc891005614f5652785c18f907913dea/ksc-1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cd7025179a17a2ddc6373234a46471740e3b814252f4c1d51a74b4bbb9fb268b",
"md5": "cfe14dac4b65361a0ce2a48dd0c6f2a7",
"sha256": "c9fb00ef423619d97dda3eec62f40712abfd7293bc754d70e22b533025a4c6ea"
},
"downloads": -1,
"filename": "ksc-1.4.tar.gz",
"has_sig": false,
"md5_digest": "cfe14dac4b65361a0ce2a48dd0c6f2a7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 213010,
"upload_time": "2025-10-13T18:46:47",
"upload_time_iso_8601": "2025-10-13T18:46:47.147218Z",
"url": "https://files.pythonhosted.org/packages/cd/70/25179a17a2ddc6373234a46471740e3b814252f4c1d51a74b4bbb9fb268b/ksc-1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-13 18:46:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kotfu",
"github_project": "ksc",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ksc"
}
