BIND(1)

🌸 NAME 🌸

okay so this is bind from the fish-shell manual, and it's literally the page that handles fish key bindings 👑

bind — handle fish key bindings

---

✨ SYNOPSIS ✨

like, here's the shape of it, bestie:

bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [--preset | --user] [-s | --silent] KEYS COMMAND ...
bind [(-M | --mode) MODE] [--preset] [--user] [--color WHEN] [KEYS]
bind [-a | --all] [--preset] [--user] [--color WHEN]
bind (-f | --function-names)
bind (-K | --key-names)
bind (-L | --list-modes)
bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] [-a | --all] | KEYS ...

---

💖 DESCRIPTION 💖

bind manages key bindings. that's the whole vibe. 🎀

If you give it both KEYS and COMMAND, bind adds (or replaces) a binding in MODE. If you give it only KEYS, bind lists any existing bindings for those keys in MODE or in all modes. And if you give it no KEYS argument at all, bind lists all bindings in MODE or in all modes. no cap. 🫶

KEYS is a comma-separated list of key names. Modifier keys can be specified by prefixing a key name with a combination of ctrl-, alt-, shift- and super- (i.e. the "windows" or "command" key). For example, pressing w while holding the Alt modifier is written as alt-w. Key names are case-sensitive; for example alt-W is the same as alt-shift-w. And ctrl-x,ctrl-e would mean pressing ctrl-x followed by ctrl-e. 💅

Some keys have names, usually because they don't have an obvious printable character representation. They are:

• the arrow keys up, down, left and right,
• backspace,
• comma (,),
• delete,
• end,
• enter,
• escape,
• f1 through f12.
• home,
• insert,
• menu,
• minus (-),
• pageup,
• pagedown,
• printscreen,
• space and
• tab,

These names are case-sensitive. yes, really. lowercase or it's not gonna hit. 🙈

An empty value ('') for KEYS designates the generic binding that will be used if nothing else matches. For most bind modes, it makes sense to bind this to the self-insert function (i.e. bind '' self-insert). This will insert any keystrokes that have no bindings otherwise. Non-printable characters are ignored by the editor, so this will not result in control sequences being inserted. very "safety first" of them honestly ✨

To find the name of a key combination you can use fish_key_reader. 🧚

COMMAND can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use bind --function-names or see below for a list of these input functions. 👑

Note: If a script changes the commandline, it should finish by calling the repaint special input function. like, fr fr, don't leave the screen looking a mess 😭

Key bindings may use "modes", which mimics vi's modal input behavior. The default mode is "default" (in vi-mode, that's vi's "normal" mode). Every key binding applies to a single mode; you can specify which one with -M MODE. If the key binding should change the mode, you can specify the new mode with -m NEW_MODE. The mode can be viewed and changed via the $fish_bind_mode variable. If you want to change the mode from inside a fish function, use set fish_bind_mode MODE. iconic. 🦋

To save custom key bindings, put the bind statements into config.fish. Alternatively, fish also automatically executes a function called fish_user_key_bindings if it exists. 🎀

---

🎀 OPTIONS 🎀

The following options are available:

• -f or --function-names — Display a list of available input functions. your lil menu of moves 💅
• -K or --key-names — Display a list of available named keys such as backspace. 🔥
• -L or --list-modes — Display a list of defined bind modes. 👑
• -M MODE or --mode MODE — Specify a bind mode that the bind is used in. Defaults to "default". If you use vi bindings, that's the command mode, what vi calls "normal" mode. bestie, it's giving normal-mode energy 🦋
• -m NEW_MODE or --sets-mode NEW_MODE — Change the current mode to NEW_MODE after this binding is executed. one binding, one whole vibe shift 💫
• -e or --erase — Erase the binding with the given sequence and mode instead of defining a new one. Multiple sequences can be specified with this flag. Specifying -a or --all with -M or --mode erases all binds in the given mode regardless of sequence. Specifying -a or --all without -M or --mode erases all binds in all modes regardless of sequence. 💀 this one goes hard, be careful
• -a or --all — See --erase. that's it, that's the whole description, go read --erase 💅
• --preset and --user — Specify if bind should operate on user or preset bindings. User bindings take precedence over preset bindings when fish looks up mappings. By default, all bind invocations work on the "user" level except for listing, which will show both levels. All invocations except for inserting new bindings can operate on both levels at the same time (if both --preset and --user are given). --preset should only be used in full binding sets (like when working on fish_vi_key_bindings). ⭐
• -s or --silent — Silences error message for unbound sequences. shhh, no thoughts, no errors 🤫
• --color WHEN — Controls when to use syntax highlighting colors when listing bindings. WHEN can be auto (the default, colorize if the output is a terminal), always, or never. 🌈 aesthetic choices matter
• -h or --help — Displays help about using this command. the classic. 🫶

---

🦋 SPECIAL INPUT FUNCTIONS 🦋

The following special input functions are available. these are the main characters of the keybinding world, honestly:

• and — only execute the next function if the previous succeeded (note: only some functions report success). conditional queen 👑
• accept-autosuggestion — accept the current autosuggestion. Returns false when there was nothing to accept. 😭 the rejection
• backward-char — move one character to the left. If the completion pager is active, select the previous completion instead. 💅
• backward-char-passive — move one character to the left, but do not trigger any non-movement-related operations. If the cursor is at the start of the commandline, does nothing. Does not change the selected item in the completion pager UI when shown. it's giving "no drama, just vibes" 🦋
• backward-token — move one argument to the left. 🎀
• backward-delete-char — deletes one character of input to the left of the cursor. bye bestie 💀
• backward-kill-token — move the argument to the left of the cursor to the killring. 💖
• backward-kill-line — move everything from the beginning of the line to the cursor to the killring. 😭 devastating
• backward-kill-path-component — move one path component to the left of the cursor to the killring. A path component is everything likely to belong to a path component, i.e. not any of the following: /={,}'":@ |;<>&, plus newlines and tabs. so specific, so iconic 🙈
• backward-kill-word — move the word to the left of the cursor to the killring, until the start of the current word (like vim's db). 🔥
• backward-kill-bigword — move the whitespace-delimited word to the left of the cursor to the killring, until the start of the current word (like vim's dB). 💅
• backward-path-component — move one path component to the left. 🧚
• backward-word — move one word to the left, stopping at the start of the previous word (like vim's b, or Emacs' M-b but differs slightly in word division rules). ⭐
• backward-bigword — move one whitespace-delimited word to the left, stopping at the start of the previous word (like vim's B). 🦋
• backward-word-end — move to the end of the previous word (like vim's ge). 🌸
• backward-bigword-end — move to the end of the previous whitespace-delimited word (like vim's gE). ✨
• beginning-of-buffer — moves to the beginning of the buffer, i.e. the start of the first line. 🎀
• beginning-of-history — move to the beginning of the history. going all the way back, bestie 💜
• beginning-of-line — move to the beginning of the line. 🫶
• begin-selection — start selecting text. highlight mode activated 💅
• cancel — close the pager if it is open, or undo the most recent completion if one was just inserted. nvm bestie, take it back 😭
• cancel-commandline — cancel the current commandline and replace it with a new empty one, leaving the old one in place with a marker to show that it was cancelled. 💀 rip
• capitalize-word — make the current word begin with a capital letter. main character energy 👑
• clear-commandline — empty the entire commandline. poof. gone. 🌈
• clear-screen — clears the screen and redraws the prompt. fresh start, new me ✨
• scrollback-push — pushes earlier output to the terminal scrollback, positioning the prompt at the top. This requires the terminal to implement the ECMA-48 SCROLL UP command and cursor position reporting. 💖 techy and specific, we love her
• complete — guess the remainder of the current token. ✨🤞
• complete-and-search — invoke the searchable pager on completion options (for convenience, this also moves backwards in the completion pager). 🦋
• delete-char — delete one character to the right of the cursor. 💅
• delete-or-exit — delete one character to the right of the cursor, or exit the shell if the commandline is empty. 😭 dramatic exit
• down-line — move down one line. ⬇️
• downcase-word — make the current word lowercase. no shouting here 🙈
• end-of-buffer — moves to the end of the buffer, i.e. the end of the last line; or if already at the end of the commandline, accept the current autosuggestion. 🎀
• end-of-history — move to the end of the history. newest stuff last, iconic 🦋
• end-of-line — move to the end of the line. 🌸
• end-selection — end selecting text. selection era over 💅
• expand-abbr — expands any abbreviation currently under the cursor. magic. ✨
• execute — run the current commandline. the moment of truth 🔥
• exit — exit the shell. goodbye bestie 😭
• forward-token — move one argument to the right. 🎀
• forward-char — move one character to the right; or if at the end of the commandline, accept the current autosuggestion. If the completion pager is active, select the next completion instead. 👑
• forward-char-passive — move one character to the right, but do not trigger any non-movement-related operations. If the cursor is at the end of the commandline, does not accept the current autosuggestion (if any). Does not change the selected item in the completion pager, if shown. just movement, no plot twists 🦋
• forward-path-component — move one path component to the right; or if at the end of the commandline, accept a path component from the current autosuggestion. ⭐
• forward-single-char — move one character to the right; or if at the end of the commandline, accept a single char from the current autosuggestion. 💖
• forward-word — hop one whole word to the right, stopping after the end of the word you're in; or, if you're already chilling at the end of the commandline, accept one word from the current autosuggestion 🫶
• forward-word-vi — same energy as forward-word, but it stops at the start of the next word (exactly like vim's w)
• forward-word-end — again like forward-word, except it stops at the end of the next word (vim's e, iykyk)
• forward-bigword — move one whitespace-delimited word to the right, stopping after the end of the current word; or if you're at the end of the commandline, accept one word from the current autosuggestion
• forward-bigword-vi — like forward-bigword, but stops at the start of the next word (vim's W)
• forward-bigword-end — like forward-bigword, but stops at the end of the next word (vim's E)
• history-pager — pull up the searchable pager on history (incremental search); or, if the history pager is already active, keep searching further backwards in time ⏳
• history-delete — permanently delete the current history item, either from the history pager or from an active up-arrow history search. Yes, permanently. No undo, bestie 💀
• history-search-backward — search the history for the previous match
• history-search-forward — search the history for the next match
• history-prefix-search-backward — search the history for the previous prefix match
• history-prefix-search-forward — search the history for the next prefix match
• history-token-search-backward — search the history for the previous matching argument
• history-token-search-forward — search the history for the next matching argument
• history-last-token-search-backward — search the history for the previous matching last argument
• history-last-token-search-forward — search the history for the next matching last argument
• forward-jump and backward-jump — read another character, then jump to its next occurrence after/before the cursor ✨
• forward-jump-till and backward-jump-till — jump to right before the next occurrence
• repeat-jump and repeat-jump-reverse — redo the last jump in the same/opposite direction
• jump-to-matching-bracket — jump to the matching bracket if the character under the cursor is a bracket; otherwise, jump to the next occurrence of any right bracket after the cursor. These are the brackets it considers: ([{}])
• jump-till-matching-bracket — same as jump-to-matching-bracket but it offsets the cursor to the right for a left bracket, and to the left for a right bracket. The offset applies to both the position you jump from and the position you jump to. In other words, the cursor keeps hopping around inside the brackets but never actually reaches them — off by 1 character, always 😭. This input function is useful for emulating the ib vi text object. Brackets considered: ([{}])
• kill-token — move the next argument to the killring
• kill-line — move everything from the cursor to the end of the line to the killring
• kill-path-component — move one path component to the killring.
• kill-selection — move the selected text to the killring
• kill-whole-line — move the line (including the following newline) to the killring. If the line is the last line, its preceding newline is also removed
• kill-inner-line — move the line (without the following newline) to the killring
• kill-word — move the next word to the killring, stopping after the end of the killed word
• kill-word-vi — move the next word to the killring, stopping at the start of the next word (vim's dw)
• kill-bigword — move the next whitespace-delimited word to the killring, stopping after the end of the current word
• kill-bigword-vi — move the next whitespace-delimited word to the killring, stopping at the start of the next word (vim's dW)
• kill-inner-word — delete the word under the cursor (vim's diw)
• kill-inner-bigword — delete the whitespace-delimited word under the cursor (vim's diW)
• kill-a-word — delete the word under the cursor plus the surrounding whitespace (vim's daw)
• kill-a-bigword — delete the whitespace-delimited word under the cursor plus the surrounding whitespace (vim's daW)
• nextd-or-forward-word — if the commandline is empty, move forward in the directory history; otherwise move one word to the right; or, if you're at the end of the commandline, accept one word from the current autosuggestion. Multitasking icon 💅
• or — only execute the next function if the previous one didn't succeed (heads up: only some functions actually report failure, so don't expect this to be a whole vibe check for everything)
• pager-toggle-search — toggles the search field if the completions pager is visible; or, if used after history-pager, search forwards in time
• prevd-or-backward-word — if the commandline is empty, move backward in the directory history; otherwise move one word to the left
• repaint — reexecutes the prompt functions and redraws the prompt (also force-repaint for backwards-compatibility)
• repaint-mode — reexecutes the fish_mode_prompt <> and redraws the prompt. This is useful for vi mode. If no fish_mode_prompt exists or it prints nothing, it acts like a normal repaint.
• self-insert — inserts the matching sequence into the command line
• self-insert-notfirst — inserts the matching sequence into the command line, unless the cursor is at the beginning
• get-key — sets fish_key to the key that was pressed to trigger this binding. Example use:

for i in (seq 0 9)
    bind $i get-key 'commandline -i "#$fish_key"' 'set -eg fish_key'
end

• suppress-autosuggestion — remove the current autosuggestion. Returns true if there was a suggestion to remove.
• swap-selection-start-stop — go to the other end of the highlighted text without changing the selection
• transpose-chars — transpose two characters to the left of the cursor
• transpose-words — transpose two words to the left of the cursor
• togglecase-char — toggle the capitalisation (case) of the character under the cursor
• togglecase-selection — toggle the capitalisation (case) of the selection
• insert-line-under — add a new line under the current line
• insert-line-over — add a new line over the current line
• up-line — move up one line
• undo and redo — revert or redo the most recent edits on the command line
• upcase-word — make the current word uppercase
• yank — insert the latest entry of the killring into the buffer
• yank-pop — rotate to the previous entry of the killring

---

✨ ADDITIONAL FUNCTIONS ✨

Okay so these next ones ship as normal functions, but they are chef's kiss particularly useful for input editing:

• up-or-search and down-or-search — move the cursor or search the history, depending on the cursor position and the current mode
• edit_command_buffer — open the visual editor (controlled by the VISUAL or EDITOR environment variables) with the current command-line contents 📝
• fish_clipboard_copy — copy the current selection to the system clipboard
• fish_clipboard_paste — paste the current selection from the system clipboard before the cursor
• fish_commandline_append — append the argument to the command-line. If the command-line already ends with the argument, this removes the suffix instead. Starts with the last command from history if the command-line is empty.
• fish_commandline_prepend — prepend the argument to the command-line. If the command-line already starts with the argument, this removes the prefix instead. Starts with the last command from history if the command-line is empty.

---

🌈 EXAMPLES 🌈

Exit the shell when ctrl+d is pressed — classic, iconic, no notes:

bind ctrl-d 'exit'

Perform a history search when pageup is pressed:

bind pageup history-search-backward

Turn on vi key bindings <#vi-mode> and rebind ctrl+c to clear the input line — main character energy fr fr:

set -g fish_key_bindings fish_vi_key_bindings
bind -M insert ctrl-c kill-whole-line repaint

Launch git diff and repaint the commandline afterwards when ctrl+g is pressed:

bind ctrl-g 'git diff' repaint

Swap tab and shift+tab, making tab focus the search field. But if the search field is already active, keep the behavior (tab cycles forward, shift+tab backward). — lowkey galaxy brain 🧠✨:

bind tab '
    if commandline --search-field >/dev/null
        commandline -f complete
    else
        commandline -f complete-and-search
    end
'
bind shift-tab '
    if commandline --search-field >/dev/null
        commandline -f complete-and-search
    else
        commandline -f complete
    end
'

---

💀 TERMINAL LIMITATIONS 💀

Bestie. Sit down. Unix terminals, like the ones fish operates in, are at heart 70s technology. Like, actual seventies. They have some limitations that applications running inside them straight-up can't workaround. Not a skill issue, just archaeology 🏺

For instance, historically the control key modifies a character by setting the top three bits to 0. This means:

• Many characters + control are indistinguishable from other keys: ctrl+i is tab, ctrl+j is newline (\n). Yeah. They're the same key as far as your terminal is concerned 🫠
• Control and shift don't work simultaneously — ctrl+X is the same as ctrl+x. No uppercase-control for you.

Other keys don't have a direct encoding, and are sent as escape sequences. For example right (→) usually sends \e\[C.

Some modern terminals support newer encodings for keys that allow distinguishing more characters and modifiers, and fish enables as many of these as it can, automatically. Slay, honestly 🎀

When in doubt, run fish_key_reader — explore what characters keyboard keys send <>. If that tells you that pressing ctrl+i sends tab, your terminal does not support these better encodings, and so fish is limited to what it sends. Not fish's fault, blame the terminal 🔥

⏱️ KEY TIMEOUT ⏱️

okay so this is the part where things get spicy 🌶️ — when you've bound a sequence of multiple characters, there is always the possibility that fish has only seen a part of it, and then it needs to disambiguate between the full sequence and part of it. like, poor fish is sitting there mid-vibe-check not knowing what you're gonna do next 😭

For example:

bind j,k 'commandline -i foo'
# or `bind jk`

will bind the sequence jk to insert "foo" into the commandline. So far so good, bestie 💅 — but when you've only pressed "j", fish doesn't know if it should insert the "j" (because of the default self-insert), or wait for the "k". it's literally standing there like 🧍 "girl... are you done or not"

You can enable a timeout for this, by setting the fish_sequence_key_delay_ms variable to the timeout in milliseconds ✨ If the timeout elapses, fish will no longer wait for the sequence to be completed, and do what it can with the characters it already has. no cap, it just commits 🫶

The escape key is a special case, because it can be used standalone as a real key or as part of a longer escape sequence, like function or arrow keys. 👀

Holding alt and something else also typically sends escape, for example holding alt+a will send an escape character and then an "a". So the escape character has its own timeout, configured with fish_escape_delay_ms 🎀

See also Key sequences. iykyk 💖

---

📜 Copyright 📜

fish-shell developers 👑

---

and that's a wrap on BIND(1) fr fr 🌈 huge thanks to the fish-shell developers for this one — page version 4.9, dated Sep 08, 2026. go forth and bind responsibly, bestie 💜🦋