Help with macOS Ctrl-n key shortcuts

New user here and quite happy so far.

I’m trying to use the ctrl-1 etc keys to select commands from the UI but they don’t seem to work. From my ~/.config/atuin/config.toml:

## use ctrl instead of alt as the shortcut modifier key for numerical UI shortcuts
## alt-0 .. alt-9
ctrl_n_shortcuts = true

I configured my terminal to use Option as Alt and confirmed that I can select commands that way. I also tried removing as much customization from my zsh as possible in case something was interfering with sending those keys:

~ $ zsh -d -f
~ $ eval "$(atuin init zsh)"

Didn’t make any difference. Any ideas?

Here is my doctor output in case it’s helpful

~ $ atuin doctor
Atuin Doctor
Checking for diagnostics

Please include the output below with any bug reports or issues

  version: 18.1.0
  sync: null
  name: zsh
  - atuin
  os: Darwin
  arch: arm64
  version: '13.4'
  - name: Macintosh HD
    filesystem: apfs
  - name: Macintosh HD
    filesystem: apfs

Ah I see there is an issue macOS + iterm ctrl-n binding issues · Issue #1577 · atuinsh/atuin · GitHub. I’ll follow that :slightly_smiling_face:

By default the option key on macOS is used as a prefix to use diacritics.

e.g.: opt+u will create the 2 dots for an umlaut. opt+u a results in ä

When you work on the commandline it might not be necessary to actually enter diacritics, since all BSD commands are comprised of 7bit ASCII characters.

So, the easiest option (pardon the pun), is to change the meaning (the control sequence that is sent to the terminal) of the option key in the terminal.

In iTerm2 you can do this like this:


In case you don’t need diacritics at all, you can change both option keys to Esc+, otherwise change only one (left or right).

And you are done.

P.S.: Dont forget to set ctrl_n_shortcuts = false

1 Like

That all makes perfect sense. I guess ctrl_n_shortcuts just don’t work as I expected it to. Thanks!

Hmm, well. ctrl+num could already have global shortcuts assigned. e.g. on my mac, those key combinations are used for switching desktops.

Additonally, there’s a difference between the numbers on the top of the keyboard and the numbers on the number block (on a full size keyboard).

But you are correct, ctrl plus another key can be tricky. These sequences often have special meanings in terminals. It is possible to circumvent possible side effects by erasing the default sequence for a key combination and re-assign them. Unfortunately terminals often do not only adhere to a standard, but also implement their own stuff, which makes it a hit and miss when dealing with this.

1 Like

Just adding to what @tessus said, but ctrl_n_shortcuts is there in case you’re using a system or terminal where it’s easier to map ctrl than alt.

Both cases can be tricky, and if I’d known how awkward this would be a few years ago I’d probably never have added the shortcuts