Skip to main content

Key binding

Atuin does not yet have full key binding customization, though we do allow some changes.

Custom up arrow filter mode

It can be useful to use a different filter or search mode on the up arrow. For example, you could use ctrl-r for searching globally, but the up arrow for searching history from the current directory only.

Set your config like this:

filter_mode_shell_up_key_binding = "directory" # or global, host, directory, etc

Disable up arrow

Our default up-arrow binding can be a bit contentious. Some people love it, some people hate it. Many people who found it a bit jarring at first have since come to love it, so give it a try! Otherwise, if you don't like it, it's easy to disable.

You can also disable either the up-arrow or Ctrl-r bindings individually, by passing --disable-up-arrow or --disable-ctrl-r to the call to atuin init:

# Bind ctrl-r but not up arrow
eval "$(atuin init zsh --disable-up-arrow)"

# Bind up-arrow but not ctrl-r
eval "$(atuin init zsh --disable-ctrl-r)"

If you do not want either key to be bound, either pass both --disable arguments, or set the environment variable ATUIN_NOBIND to any value before the call to atuin init:

## Do not bind any keys
# Either:
eval "$(atuin init zsh --disable-up-arrow --disable-ctrl-r)"

# Or:
export ATUIN_NOBIND="true"
eval "$(atuin init zsh)"

You can then choose to bind Atuin if needed, do this after the call to init.

Ctrl-n key shortcuts

macOS does not have an Alt key, although terminal emulators can often be configured to map the Option key to be used as Alt. However, remapping Option this way may prevent typing some characters, such as using Option-3 to type # on the British English layout. For such a scenario, set the ctrl_n_shortcuts option to true in your config file to replace Alt-0 to Alt-9 shortcuts with Ctrl-0 to Ctrl-9 instead:

# Use Ctrl-0 .. Ctrl-9 instead of Alt-0 .. Alt-9 UI shortcuts
ctrl_n_shortcuts = true


If you'd like to customize your bindings further, it's possible to do so with custom shell config:

Atuin defines the ZLE widget "_atuin_search_widget"

export ATUIN_NOBIND="true"
eval "$(atuin init zsh)"

bindkey '^r' _atuin_search_widget

# depends on terminal mode
bindkey '^[[A' _atuin_search_widget
bindkey '^[OA' _atuin_search_widget


export ATUIN_NOBIND="true"
eval "$(atuin init bash)"

# bind to ctrl-r, add any other bindings you want here too
bind -x '"\C-r": __atuin_history'


set -gx ATUIN_NOBIND "true"
atuin init fish | source

# bind to ctrl-r in normal and insert mode, add any other bindings you want here too
bind \cr _atuin_search
bind -M insert \cr _atuin_search


$env.ATUIN_NOBIND = true
atuin init nu | save -f ~/.local/share/atuin/ #make sure you created the directory beforehand with `mkdir ~/.local/share/atuin/`
source ~/.local/share/atuin/

#bind to ctrl-r in emacs, vi_normal and vi_insert modes, add any other bindings you want here too
$env.config = (
$env.config | upsert keybindings (
| append {
name: atuin
modifier: control
keycode: char_r
mode: [emacs, vi_normal, vi_insert]
event: { send: executehostcommand cmd: (_atuin_search_cmd) }

Atuin UI shortcuts

ctrl + rCycle through filter modes
ctrl + sCycle through search modes
alt + 1 to alt + 9Select item by the number located near it
ctrl + c / ctrl + d / ctrl + g / escReturn original
ctrl + ⬅︎ / alt + bMove the cursor to the previous word
ctrl + ➡️ / alt + fMove the cursor to the next word
ctrl + h / ctrl + b / ⬅︎Move the cursor to the left
ctrl + l / ctrl + f / ➡️Move the cursor to the right
ctrl + a / homeMove the cursor to the start of the line
ctrl + e / endMove the cursor to the end of the line
ctrl + backspace / ctrl + alt + backspaceRemove the previous word / remove the word just before the cursor
ctrl + delete / ctrl + alt + deleteRemove the next word or the word just after the cursor
ctrl + wRemove the word before the cursor even if it spans across the word boundaries
ctrl + uClear the current line
ctrl + n / ctrl + j / ⬆Select the next item on the list
ctrl + p / ctrl + k / ⬇Select the previous item on the list
page downScroll search results one page down
page upScroll search results one page up
enterSelect highlighted item
⬇ (with no entry selected)Return original or return query depending on settings
Select the next item on the list