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.

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

Shortcut	Action
enter	Execute selected item
tab	Select item and edit
ctrl + r	Cycle through filter modes
ctrl + s	Cycle through search modes
alt + 1 to alt + 9	Select item by the number located near it
ctrl + c / ctrl + d / ctrl + g / esc	Return original
ctrl + y	Copy selected item to clipboard
ctrl + ⬅︎ / alt + b	Move the cursor to the previous word
ctrl + ➡️ / alt + f	Move the cursor to the next word
ctrl + b / ⬅︎	Move the cursor to the left
ctrl + f / ➡️	Move the cursor to the right
ctrl + a / home	Move the cursor to the start of the line
ctrl + e / end	Move the cursor to the end of the line
ctrl + backspace / ctrl + alt + backspace	Remove the previous word / remove the word just before the cursor
ctrl + delete / ctrl + alt + delete	Remove the next word or the word just after the cursor
ctrl + w	Remove the word before the cursor even if it spans across the word boundaries
ctrl + u	Clear 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 down	Scroll search results one page down
page up	Scroll 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:

Shortcut	Mode	Action
k	Normal	Selects the next item on the list
j	Normal	Selects the previous item on the list
i	Normal	Enters insert mode
Esc	Insert	Enters normal mode