Skip to 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!

It becomes much more powerful if you consider binding a different filter mode to the up arrow. For example, on “up” Atuin can default to searching all history for the current directory only, while ctrl-r searches history globally. See the config for more.

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 in your shell config file:

An example for zsh:

# 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.

Nushell Only: The up-arrow keybinding is disabled by default for Nushell until #1025 is resolved.

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

zsh

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

Atuin defines the ZLE widgets “atuin-search” and “atuin-up-search”. The latter can be used for the keybindings to the up key and similar keys.

Note: instead use the widget names “_atuin_search_widget” and “_atuin_up_search_widget”, respectively, in atuin < 18.0

export ATUIN_NOBIND="true"
eval "$(atuin init zsh)"
bindkey '^r' atuin-search
# bind to the up key, which depends on terminal mode
bindkey '^[[A' atuin-up-search
bindkey '^[OA' atuin-up-search

For the keybindings in vi mode, “atuin-search-viins”, “atuin-search-vicmd”, “atuin-up-search-viins”, and “atuin-up-search-vicmd” (atuin >= 18.0) can be used in combination with the config “keymap_mode” (atuin >= 18.0) to start the Atuin search in respective keymap modes.

bash

Atuin provides a bindable shell function “_atuin_history” for keybindings in Bash. The flag --shell-up-key-binding can be optionally specified to the first argument for keybindings to the up key or similar keys.

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'
# bind to the up key, which depends on terminal mode
bind -x '"\e[A": __atuin_history --shell-up-key-binding'
bind -x '"\eOA": __atuin_history --shell-up-key-binding'

For the keybindings in the vi editing mode, the options --keymap-mode=vim-insert and --keymap-mode=vim-normal (atuin >= 18.0) can be additionally specified to the shell function __atuin_history in combination with the config “keymap_mode” (atuin >= 18.0) to start the Atuin search in respective keymap modes.

fish

Edit key bindings in FISH shell by adding the following to ~/.config/fish/config.fish

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

For the up keybinding, _atuin_bind_up can be used instead of _atuin_search.

Adding the useful alternative key binding of CTRL-up is tricky and determined by the terminals adherence to terminfo(5).

Conveniently FISH uses a command to capture keystrokes and advises you of the exact command to add for your specific terminal. In your terminal, run fish_key_reader then punch the desired keystroke/s.

For example, in Gnome Terminal the output to CTRL-upkey is bind \e\[1\;5A 'do something'

So, adding this to the above sample, bind \e\[1\;5A _atuin_search will provide the additional search keybinding.

nu

$env.ATUIN_NOBIND = true
atuin init nu | save -f ~/.local/share/atuin/init.nu #make sure you created the directory beforehand with `mkdir ~/.local/share/atuin/init.nu`
source ~/.local/share/atuin/init.nu
#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 (
$env.config.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

ShortcutAction
enterExecute selected item
tabSelect item and edit
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 + yCopy selected item to clipboard
ctrl + ⬅︎ / alt + bMove the cursor to the previous word
ctrl + ➡️ / alt + fMove the cursor to the next word
ctrl + b / ⬅︎Move the cursor to the left
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
⬇ (with no entry selected)Return original or return query depending on settings
Select the next item on the list

Vim mode

If vim is enabled in the config, the following keybindings are enabled:

ShortcutModeAction
kNormalSelects the next item on the list
jNormalSelects the previous item on the list
iNormalEnters insert mode
EscInsertEnters normal mode