Getting Started

Keymando is a powerful, all-purpose tool that allows for open-ended customization. Here are a few of the basics to help you get started.

Quick Links: Configuration | Key Mapping | Commands | Window Management | Mouse Manipulation



Keymando’s configuration is simply stored in a file called keymandorc.rb, following the popular ‘rc’ convention. All the following examples can be put directly into this file.

You can find where your keymandorc.rb file is stored by going to Setup in the Keymando menu.

The default location is:

~/Library/Application Support/Keymando/keymandorc.rb

You can also quickly edit your keymandorc.rb file by going to the Edit Config in the Keymando menu. This will open your config file with your default ruby file editor.

Pro Tip Add your configuration files to a source control system to backup and share your settings.

Two other important settings are the Keymando directory and the Plugins directory. The Keymando directory is a location where any additional files can be evaluated, similary to your keymandorc.rb. This allows your to break your configuration into multiple files. The default Keymando directory is here:

~/Library/Application Support/Keymando/

The Plugins directory is where plugins are loaded from. The default location is

~/Library/Application Support/Keymando/Plugins
Pro Tip You can change your configuration to use any location you like, such as ~/.keymando.

Key Mapping

Key mapping allows you to map key(s) to other key(s) or to actions.

Vim users will appreciate this example.

map "<Ctrl-[>", "<Escape>"

You can also map keys to nil to effectively disable a key or keys. This is useful for preventing unwanted quitting of applications.

Disable keys

only /iTerm/ do
  map "<Cmd-w>", nil
  map "<Cmd-q>", nil
  map "<Cmd-r>", nil
  map "<Cmd-t>", nil


In order for changes to take affect, the keymandorc.rb must be reloaded. This can be accomplished via the Reload Config menu item or the reload method.

map '<Ctrl-r>' do
  alert('Reloaded Successfully') if reload

Application Specific Key Mapping

As we saw in the previous example, Keymando’s key mapping allows you to specify filters with only and except. These filters take a list of strings and/or regular expressions to match the currently active application.

except /iTerm/, "MacVim" do
  map "<Ctrl-j>", "<Down>"
  map "<Ctrl-k>", "<Up>"
  map "<Ctrl-h>", "<Left>"
  map "<Ctrl-l>", "<Right>"
only /Outlook/ do
  nmap "#", "<Delete>"
  nmap "c", "<Cmd-n>"
  nmap "y" do
  nmap "v" do


nmap specifies a ‘normal’ mode key mapping, that is, not in a textbox.

imap specifies an ‘insert’ mode key mapping, that is, inside a textbox.

Note: Not all applications support `imap` key mapping so your milage may vary.


Keymando features reusable units of execution called commands and comes with many included by default. Commands like “Show Current App Menus”, “Lock the Screen”, and “Window - Move to Fullscreen”.

The easiest way to use commands is to map a key combination to Commands.run_registered_command .

Think of an application launcher for commands.

map "<Cmd- >", Commands.run_registered_command

Another good key mapping to have is the run_last_command.

map "<Cmd-.>", Commands.run_last_command

You can also “register” commands apart from key mappings.

command "Quit current application" do

command "Volume Up" do
  `osascript -e 'set volume output volume (output volume of (get volume settings) + 7)'`

command "Volume Down" do
  `osascript -e 'set volume output volume (output volume of (get volume settings) - 7)'`

Creating a command this will make is available in the Commands.run_registered_command dialog.

Using Commands Programatically

You can access and run commands in your scripts via the follow convention.


Window Management

Keymando comes with window manipulation commands out of the box.

Here are just a few:

Window - Move to Full Screen
Window - Move to Top Left
Window - Move to Top Left
Window - Bump Left by 5

See Commands for the basic on how to use commands.

Pro Tip Re-running a command like "Window - Move to Full Screen" will cycle between monitors.

Mouse Manipulation



Start at login



  toggle "<Ctrl-E>"

If you’d like more in-depth documentation, check out the latest build’s documention.