Nickolai Tchesnokov

MacOS cmd key bindings in Nvim

< nvim />, < productivity />

One of the main tools I use on a daily basis is Neovim and the terminal. However, there is no out of the box method to map the Cmd key when using Neovim in the terminal.

A simple solution is to use Karabiner to remap keys globally. This works well for remapping something like arrow keys. However, the main issue with this approach is application compatibility. For example, remapping the Cmd+S shortcut globally to work in Nvim would cause problems in other programs that rely on that combination to save files. Therefore this approach should be used with caution and only for key mappings that you are certain will not have conflicts with other programs.

Another potential solution is to use MacVim, a GUI-based version of Vim that integrates better with macOS. MacVim comes with standard macOS Cmd key shortcuts out of the box. However, this approach doesn’t actually solve the issue of mapping the Cmd key in Nvim running in the terminal. Instead, it’s more of a workaround that avoids the problem by using a different tool altogether. This may not be a helpful solution for those who prefer to work within the terminal environment and need to configure Nvim.

The ideal solution would be to find a way to map the Command key directly within the Nvim configuration, without relying on system-level remapping or switching to a different Vim-based application. Fortunately, I’ve found a solution that involves using my terminal emulator of choice, iTerm2.

While this solution isn’t as clean as I’d prefer, it has worked well for me over the past couple of years without any issues. The process involves configuring key mappings within iTerm2 to allow the use of the Command key in Nvim. It’s a bit tedious to set up, but it provides the functionality I need without affecting the rest of my system.

Mapping the Command Key in Nvim using iTerm2

To map the Command key in Neovim when using the iTerm2 terminal, it essentially requires a double layer of key mappings. You’ll need to configure the key bindings in both iTerm2 and your Nvim setup to get everything working.

  1. iTerm2 Key Mappings: The first step is to set up the key bindings within iTerm2 itself. This allows you to remap the Command key to send the necessary hex codes that Nvim can recognise.
  2. Nvim Configuration: The second part involves configuring your Nvim setup to actually use the Command key bindings that you mapped in iTerm2. This ensures the key combinations work as expected within your Nvim environment.

iTerm configuration

a. In iTerm2, navigate to:

  • Preferences > Profiles and,
  • Select the profile you wish to modify (or create a new one).

b. In the selected Profile, navigate to:

  • Keys > Key Mappings
  • This area lists all key bindings configured for the selected profile.

c. Now we want to add new keybinds to this profile. To add a new keybind:

  • Click the + button.
  • Input the keyboard shortcut you want to map.
  • Select the action Send Hex code from the dropdown menu.
  • Input the hexcode sequence you would like to map your shortcut to.

When you select the “Send Hex Code” action, you’re instructing iTerm2 to send a specific sequence of hexadecimal values to the terminal, representing the literal keyboard input you want to simulate.

For example, if you wanted to make a key binding that sends the word “foo” using hex codes, you’ll want to convert each letter into its ASCII representation in hexadecimal. For “foo”, this would be 0x66 0x6f 0x6f.

This method allows for a vast range of inputs to be encoded and recognised by iTerm2 and other terminal emulators. A full ASCII character chart, including the Hexadecimal conversion can be found here.

In our case, we want to choose hex code sequences that are both unique and unlikely to overlap with default or commonly used shortcuts. This is important because it prevents your custom key bindings from conflicting with existing bindings, ensuring that your intended actions are executed without interference.

Let’s map two shortcuts as an example using some uncommon sequences:

  • Map Cmd+c to 0x1b 0x45 0x5d
  • Map Cmd+v to 0x1b 0x5d 0x47

Where:

  • 0x1b 0x45 0x5d is ESC E ]
  • 0x1b 0x5d 0x47 is ESC ] G

You can choose any sequence you want but make sure it is unique to your system.

Nvim configuration

The last step is to configure your Nvim setup to use the Command key bindings you’ve mapped in iTerm2. Based on the example provided above, this involves adding the following lines to your Nvim configuration:

-- Cmd+c to copy (yank) in normal mode
keymap.set("n", "<Esc>E]", "yy") 

-- Cmd+v to paste in normal mode
keymap.set("n", "<Esc>]G", "p")

In this example, we’re using the keymap.set() function to bind the ASCII representation of the hex codes we configured in iTerm2 to the corresponding Nvim commands for copy yy and paste p in normal mode.

The <Esc>E] and <Esc>]G sequences match the hex codes 0x1b 0x45 0x5d and 0x1b 0x5d 0x47 that we mapped in the previous step for Cmd+c and Cmd+v, respectively.

By adding these mappings to your Nvim config, you can now use the Cmd+c and Cmd+v key combinations within Nvim, and they will perform the expected copy and paste actions.