ZSHZLE(1)

📦

version 5.9.2 · 5 versions

5.9.2 · arch rolling, nixpkgs unstable (latest)
5.9.1 · nixos 26.05
5.8 · centos-stream 9
5.8.1 · ubuntu jammy
5.9 · alpine 3.22, alpine 3.23, alpine 3.24, centos-stream 10, debian bookworm, debian trixie, fedora 43, fedora 44, opensuse-leap 16.0, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

zshzle — zsh command line editor. Yep bestie, this is the ZSHZLE(1) page from the General Commands Manual, and we're about to make your command line editing era absolutely iconic. 💅✨

✨ DESCRIPTION ✨

Okay so picture this: if the ZLE option is set — and yes, it's set by default in interactive shells — and the shell input is attached to the terminal, then the user can edit command lines. Main character energy fr fr. 💖

There are two display modes, and the first one is multiline mode, which is the default. It only works if the TERM parameter is set to a valid terminal type that can move the cursor up. The second one is single line mode, and it's used if TERM is invalid or incapable of moving the cursor up, or if the SINGLE_LINE_ZLE option is set. This mode is similar to ksh, and it uses no termcap sequences. Also: if TERM is "emacs", the ZLE option will be unset by default. Noted. 🫶

The parameters BAUD, COLUMNS, and LINES are also used by the line editor. See Parameters Used By The Shell in zshparam(1). 🌈

The parameter zle_highlight is also used by the line editor; see Character Highlighting below. Highlighting of special characters and the region between the cursor and the mark — as set with set-mark-command in Emacs mode, or by visual-mode in Vi mode — is enabled by default; consult this reference for more information. And for the irascible conservatives in the chat: yes, all highlighting may be disabled by the following setting:

zle_highlight=(none)

In many places, references are made to the numeric argument. This can by default be entered in emacs mode by holding the alt key and typing a number, or pressing escape before each digit, and in vi command mode by typing the number before entering a command. Generally the numeric argument causes the next command entered to be repeated the specified number of times, unless otherwise noted below; this is implemented by the digit-argument widget. See also the Arguments subsection of the Widgets section for some other ways the numeric argument can be modified. 🔥

🔑 KEYMAPS 🔑

A keymap in ZLE contains a set of bindings between key sequences and ZLE commands. The empty key sequence cannot be bound. Periodt. 🎀

There can be any number of keymaps at any time, and each keymap has one or more names. If all of a keymap's names are deleted, it disappears. bindkey can be used to manipulate keymap names. 💫

Initially, there are eight keymaps:

emacs — EMACS emulation
viins — vi emulation - insert mode
vicmd — vi emulation - command mode
viopp — vi emulation - operator pending
visual — vi emulation - selection active
isearch — incremental search mode
command — read a command name
.safe — fallback keymap

The .safe keymap is special. It can never be altered, and the name can never be removed. However, it can be linked to other names, which can be removed. In the future other special keymaps may be added; users should avoid using names beginning with . for their own keymaps. 🦋

In addition to these names, either emacs or viins is also linked to the name main. If one of the VISUAL or EDITOR environment variables contain the string vi when the shell starts up then it will be viins, otherwise it will be emacs. bindkey's -e and -v options provide a convenient way to override this default choice. 💜

When the editor starts up, it will select the main keymap. If that keymap doesn't exist, it will use .safe instead. 🙈

In the .safe keymap, each single key is bound to self-insert, except for ^J (line feed) and ^M (return) which are bound to accept-line. This is deliberately not pleasant to use; if you are using it, it means you deleted the main keymap, and you should put it back. 😭

📖 Reading Commands 📖

When ZLE is reading a command from the terminal, it may read a sequence that is bound to some command and is also a prefix of a longer bound string. In this case ZLE will wait a certain time to see if more characters are typed, and if not (or they don't match any longer string) it will execute the binding. This timeout is defined by the KEYTIMEOUT parameter; its default is 0.4 sec. There is no timeout if the prefix string is not itself bound to a command. ⏳

The key timeout is also applied when ZLE is reading the bytes from a multibyte character string when it is in the appropriate mode. (This requires that the shell was compiled with multibyte mode enabled; typically also the locale has characters with the UTF-8 encoding, although any multibyte encoding known to the operating system is supported.) If the second or a subsequent byte is not read within the timeout period, the shell acts as if ? were typed and resets the input state. 🌸

As well as ZLE commands, key sequences can be bound to other strings, by using bindkey -s. When such a sequence is read, the replacement string is pushed back as input, and the command reading process starts again using these fake keystrokes. This input can itself invoke further replacement strings, but in order to detect loops the process will be stopped if there are twenty such replacements without a real command being read. 🔁

A key sequence typed by the user can be turned into a command name for use in user-defined widgets with the read-command widget, described in the subsection Miscellaneous of the section Standard Widgets below. 👑

🏠 Local Keymaps 🏠

While for normal editing a single keymap is used exclusively, in many modes a local keymap allows for some keys to be customised. For example, in an incremental search mode, a binding in the isearch keymap will override a binding in the main keymap but all keys that are not overridden can still be used. ✨

If a key sequence is defined in a local keymap, it will hide a key sequence in the global keymap that is a prefix of that sequence. An example of this occurs with the binding of iw in viopp as this hides the binding of i in vicmd. However, a longer sequence in the global keymap that shares the same prefix can still apply so for example the binding of ^Xa in the global keymap will be unaffected by the binding of ^Xb in the local keymap. 🧚

🛠️ ZLE BUILTINS 🛠️

The ZLE module contains three related builtin commands. The bindkey command manipulates keymaps and key bindings; the vared command invokes ZLE on the value of a shell parameter; and the zle command manipulates editing widgets and allows command line access to ZLE commands from within shell functions. 💖

bindkey [ options ] -l [ -L ] [ keymap ... ]
bindkey [ options ] -d
bindkey [ options ] -D keymap ...
bindkey [ options ] -A old-keymap new-keymap
bindkey [ options ] -N new-keymap [ old-keymap ]
bindkey [ options ] -m
bindkey [ options ] -r in-string ...
bindkey [ options ] -s in-string out-string ...
bindkey [ options ] in-string command ...
bindkey [ options ] [ in-string ]

bindkey's options can be divided into three categories: keymap selection for the current command, operation selection, and others. The keymap selection options are:

-e — Selects keymap emacs for any operations by the current command, and also links emacs to main so that it is selected by default the next time the editor starts.
-v — Selects keymap viins for any operations by the current command, and also links viins to main so that it is selected by default the next time the editor starts.
-a — Selects keymap vicmd for any operations by the current command.
-M keymap — The keymap specifies a keymap name that is selected for any operations by the current command.

If a keymap selection is required and none of the options above are used, the main keymap is used. Some operations do not permit a keymap to be selected, namely: 🚫

-l — List all existing keymap names; if any arguments are given, list just those keymaps.

If the -L option is also used, list in the form of bindkey commands to create or link the keymaps. bindkey -lL main shows which keymap is linked to main, if any, and hence if the standard emacs or vi emulation is in effect. This option does not show the .safe keymap because it cannot be created in that fashion; however, neither is bindkey -lL .safe reported as an error, it simply outputs nothing. 🫶

-d — Delete all existing keymaps and reset to the default state.
-D keymap ... — Delete the named keymaps.
-A old-keymap new-keymap — Make the new-keymap name an alias for old-keymap, so that both names refer to the same keymap. The names have equal standing; if either is deleted, the other remains. If there is already a keymap with the new-keymap name, it is deleted.
-N new-keymap [ old-keymap ] — Create a new keymap, named new-keymap. If a keymap already has that name, it is deleted. If an old-keymap name is given, the new keymap is initialized to be a duplicate of it, otherwise the new keymap will be empty.

To use a newly created keymap, it should be linked to main. Hence the sequence of commands to create and use a new keymap mymap initialized from the emacs keymap (which remains unchanged) is:

bindkey -N mymap emacs
bindkey -A mymap main

Note that while bindkey -A newmap main will work when newmap is emacs or viins, it will not work for vicmd, as switching from vi insert to command mode becomes impossible. 💀

The following operations act on the main keymap if no keymap selection option was given:

-m — Add the built-in set of meta-key bindings to the selected keymap. Only keys that are unbound or bound to self-insert are affected.
-r in-string ... — Unbind the specified in-strings in the selected keymap. This is exactly equivalent to binding the strings to undefined-key.

When -R is also used, interpret the in-strings as ranges.

When -p is also used, the in-strings specify prefixes. Any binding that has the given in-string as a prefix, not including the binding for the in-string itself, if any, will be removed. For example,

bindkey -rpM viins '^['

will remove all bindings in the vi-insert keymap beginning with an escape character (probably cursor keys), but leave the binding for the escape character itself (probably vi-cmd-mode). This is incompatible with the option -R. 🔥

-s in-string out-string ... — pairs them up, bestie: each in-string gets bound to its matching out-string. Type in-string and the out-string gets pushed back and treated as input to the line editor. And if you're also using -R, the in-strings are read as ranges instead. 💫 Heads up tho: both in-string and out-string get interpreted the same way, which is the whole escape-sequence tea described down below.
in-string command ... — binds each in-string to each command. With -R, the in-strings are ranges again.
[ in-string ] — the listing era ✨. If you give an in-string, you get the binding for that string in the selected keymap. No in-string? Then every key binding in the selected keymap gets dumped out. (Special case alert 🎀: if -e or -v is used alone, the keymap is not displayed — the implicit linking of keymaps is literally the only thing that happens.)

With -p, the in-string must be present. The listing then shows every binding that has the given key sequence as a prefix, and it does not include bindings for the key sequence itself.

With -L, the list comes out in the form of bindkey commands you could run to create those key bindings. 🫶

When -R is used like we said, a valid range is two characters with an optional - between them. Every character between the two you specified — inclusive, babes — gets bound as specified. 💅

For either in-string or out-string, these escape sequences are recognised:

\a — bell character
\b — backspace
\e, \E — escape
\f — form feed
\n — linefeed (newline)
\r — carriage return
\t — horizontal tab
\v — vertical tab
\NNN — character code in octal
\xNN — character code in hexadecimal
\uNNNN — unicode character code in hexadecimal
\UNNNNNNNN — unicode character code in hexadecimal
\M[-]X — character with meta bit set
\C[-]X — control character
^X — control character

In all other cases, \ escapes the character right after it. Delete is written as ^?. And clock this: \M^? and ^\M? are not the same thing, and — unlike emacs — the bindings \M-X and \eX are entirely distinct, even though bindkey -m initialises them to the same bindings. 😭 no cap, they're different.

🌸 vared

vared [ -Aacghe ] [ -p prompt ] [ -r rprompt ]
      [ -M main-keymap ] [ -m vicmd-keymap ]
      [ -i init-widget ] [ -f finish-widget ]
      [ -t tty ] name

Okay so here's the vibe: the value of the parameter name gets loaded into the edit buffer, and the line editor is invoked. When the editor exits, name is set to the string value the editor returned. 💖

Give -c and the parameter gets created if it doesn't already exist.
-a can be given with -c to create an array parameter, or -A to create an associative array.
If the type of an existing parameter doesn't match the type to be created, the parameter is unset and recreated. 💀
-g may be given to suppress warnings from the WARN_CREATE_GLOBAL and WARN_NESTED_VAR options.

If you're editing an array or an array slice, separator characters as defined in $IFS are shown quoted with a backslash — and so are backslashes themselves. Conversely, when the edited text gets split into an array, a backslash quotes an immediately following separator character or backslash; no other special handling of backslashes happens, and no handling of quotes happens either. 🙈

Individual elements of existing array or associative array parameters can be edited by using subscript syntax on name. New elements are created automatically, even without -c. ✨

-p — the following string is taken as the prompt to display at the left.
-r — the following string is the prompt to display at the right.
-h — the history can be accessed from ZLE.
-e — typing ^D (Control-D) on an empty line causes vared to exit immediately with a non-zero return value.

The -M option gives a keymap to link to the main keymap during editing, and -m gives a keymap to link to the vicmd keymap during editing. For vi-style editing, this lets a pair of keymaps override viins and vicmd. For emacs-style editing, only -M is normally needed, but -m may still be used. On exit, the previous keymaps get restored. 🫶

vared calls the usual zle-line-init and zle-line-finish hooks before and after it takes control. Using -i and -f, you can replace these with other custom widgets. iconic.

If -t tty is given, tty is the name of a terminal device to be used instead of the default /dev/tty. If tty doesn't refer to a terminal, an error is reported. ⚠️

🌈 zle

zle
zle -l [ -L | -a ] [ string ... ]
zle -D widget ...
zle -A old-widget new-widget
zle -N widget [ function ]
zle -f flag [ flag... ]
zle -C widget completion-widget function
zle -R [ -c ] [ display-string ] [ string ... ]
zle -M string
zle -U string
zle -K keymap
zle -F [ -L | -w ] [ fd [ handler ] ]
zle -I
zle -T [ tc function | -r tc | -L ]
zle widget [ -n num ] [ -f flag ] [ -Nw ] [ -K keymap ] args ...

The zle builtin does a whole bunch of different things concerning ZLE, and honestly it's giving main character energy with how many forms it has. 👑

With no options and no arguments, only the return status gets set. It's zero if ZLE is currently active and widgets could be invoked using this builtin command, and non-zero otherwise. Note: even if a non-zero status is returned, zle may still be active as part of the completion system — but that doesn't allow direct calls to ZLE widgets. 😭

Otherwise, which operation it performs depends on its options:

-l [ -L | -a ] [ string ] — lists all existing user-defined widgets. With -L, it lists them in the form of zle commands that would create the widgets.

Combined with -a, all widget names are listed, including the builtin ones. In that case -L is ignored. 🙈

If at least one string is given, and -a is present or -L is not used, nothing gets printed. The return status is zero if all the strings are names of existing widgets, and non-zero if at least one string isn't the name of a defined widget. If -a is also present, all widget names are used for the comparison including builtin widgets; otherwise only user-defined widgets are used.

If at least one string is present and -L is used, user-defined widgets matching any string are listed in the form of zle commands to create the widgets. ✨

-D widget ... — deletes the named widgets. bye bestie 💅
-A old-widget new-widget — makes the name new-widget an alias for old-widget, so both names refer to the same widget. The names have equal standing; if either is deleted, the other remains. If there's already a widget with the new-widget name, it gets deleted. 🎀
-N widget [ function ] — creates a user-defined widget. If a widget with that name already exists, it's overwritten. When the new widget is invoked from within the editor, the specified shell function is called. If no function name is given, it defaults to the same name as the widget. For more, see the section Widgets below. 🌟
-f flag [ flag... ] — sets various flags on the running widget. Possible values for flag are:
- yank — says the widget has yanked text into the buffer. If the widget is wrapping an existing internal widget, no further action is necessary, but if it inserted the text manually, then it should also take care to set YANK_START and YANK_END correctly. yankbefore does the same but is used when the yanked text appears after the cursor.
- kill — says text has been killed into the cutbuffer. When you repeatedly invoke a kill widget, text is appended to the cutbuffer instead of replacing it, but when wrapping such widgets it's necessary to call zle -f kill to keep that effect. 🔥
- vichange — says the widget represents a vi change that can be repeated as a whole with vi-repeat-change. The flag should be set early in the function, before inspecting the value of NUMERIC or invoking other widgets. This has no effect for a widget invoked from insert mode. If insert mode is active when the widget finishes, the change extends until next returning to command mode.
-C widget completion-widget function — creates a user-defined completion widget named widget. It behaves like the built-in completion widget whose name is given as completion-widget. To generate the completions, the shell function function is called. For more, see zshcompwid(1). 🦋
-R [ -c ] [ display-string ] [ string ... ] — redisplays the command line. If a display-string is given and isn't empty, it's shown in the status line (immediately below the line being edited).

If the optional strings are given, they're listed below the prompt the same way completion lists get printed. If no strings are given but -c is used, such a list is cleared. ✨

Note that immediately after those widgets return, the command line gets redisplayed and all those strings you were showing get erased 😭 so this option is genuinely only useful for widgets that don't exit straight after using it. Like, think about it.

This command can also be called safely outside user-defined widgets — if zle is active the display gets refreshed, and if zle isn't active the command just does nothing at all. In that case there'll usually be no other arguments.

The status is zero if zle was active, else one. 💅

-M string — so this is like -R (string shows up below the command line) but not like -R in one key way: the string does not go into the status line, it just gets printed normally below the prompt instead. Which means it's still there after the widget returns, until subsequent commands overwrite it. Iconic behaviour honestly.
-U string — pushes the characters in string onto ZLE's input stack 🫶. After the widget that's currently running finishes, ZLE behaves exactly as if the user typed those characters themselves. It's a stack, so if you use this repeatedly the last string pushed gets processed first — but the characters within each string still get processed in the order they appear in the string. Order matters, bestie.
-K keymap — selects the keymap named keymap. If there's no such keymap you get an error message, sorry 🥲. This selection affects how following keystrokes are interpreted within this invocation of ZLE. Any following invocation (like, the next command line) starts fresh with the main keymap selected. It does not persist. Periodt.
-F [ -L | -w ] [ fd [ handler ] ] — only available if your system supports one of the poll or select system calls; most modern systems do, so you're probably fine ✨.

Installs handler (the name of a shell function) to handle input from file descriptor fd. If you install a handler for an fd that's already handled, the existing handler gets replaced. You can have any number of handlers for any number of readable file descriptors. Heads up though: zle makes no attempt to check whether the fd is actually readable when you install the handler, and the user has to make their own arrangements for handling the fd while zle is not active.

When zle is trying to read data it looks at both the terminal and the list of handled fds. If data becomes available on a handled fd, zle calls handler with the fd that's ready for reading as the first argument. Normally that's the only argument, but if an error got detected, a second argument gives you the details: hup for a disconnect, nval for a closed or otherwise invalid descriptor, or err for any other condition. Systems that support only the select system call always use err.

If you also give the -w option, the handler is a line editor widget instead — typically a shell function turned into a widget with zle -N. In that case handler gets to use all the facilities of zle to update the current editing line 🎀. But note: because handling the fd happens at a low level, changes to the display won't automatically appear — the widget should call zle -R to force a redisplay. And as of this writing, widget handlers only support a single argument and are therefore never passed a string for error state, so widgets have to be prepared to test the descriptor themselves.

If either type of handler produces output to the terminal, it should call zle -I before doing so (see below 👇). Handlers should not attempt to read from the terminal.

If no handler is given but an fd is present, any handler for that fd gets removed. And if there isn't one, an error message is printed and status 1 is returned.

If no arguments are given at all, or the -L option is supplied, a list of handlers is printed in a form you can store and execute later. An fd (but not a handler) can optionally be given with -L — in that case the function lists the handler if there is one, and otherwise silently returns status 1.

⚠️ Use this feature with care, fr fr. Activity on one of the fds that isn't properly handled can make the terminal unusable 💀. And removing an fd handler from inside a signal trap may cause unpredictable behaviour. You've been warned.

Here's a simple example of the whole feature in action 🦋. A connection to a remote TCP port is created with the ztcp command; peep the description of the zsh/net/tcp module in zshmodules(1). Then a handler gets installed that simply prints out any data arriving on that connection. Note that select will say the file descriptor needs handling if the remote side has closed the connection — we deal with that by testing for a failed read.

if ztcp pwspc 2811; then
  tcpfd=$REPLY
  handler() {
    zle -I
    local line
    if ! read -r line <&$1; then
      # select marks this fd if we reach EOF,
      # so handle this specially.
      print "[Read on fd $1 failed, removing.]" >&2
      zle -F $1
      return 1
    fi
    print -r - $line
  }
  zle -F $tcpfd handler
fi

-I — unusually, this one is most useful outside ordinary widget functions, though you can use it inside one too if you need normal output to the terminal. It invalidates the current zle display in preparation for output — typically from a trap function. It has no effect if zle isn't active. When a trap exits, the shell checks whether the display needs restoring, which is why the following prints output without disturbing the line you're editing 🌸:

TRAPUSR1() {
  # Invalidate zle display
  [[ -o zle ]] && zle -I
  # Show output
  print Hello
}

In general the trap function may need to test whether zle is active before using this method (like the example does), because the zsh/zle module might not even be loaded — and if it isn't, the command can just be skipped.

You can call zle -I several times before control goes back to the editor; the display only gets invalidated the first time, to minimise disruption ✨.

Note that there are normally better ways to mess with the display from inside zle widgets — see, for example, zle -R above.

The returned status is zero if zle was invalidated, even if that happened via a previous zle -I call or a system notification. If you want to test whether a zle widget can be called at this point, just run zle with no arguments and check the return status. iykyk 💅

-T — used to add, list or remove internal transformations on the processing the line editor does. It's typically only for debugging or testing, so it's lowkey of little interest to the general user 🙈.

zle -T transformation func says the given transformation (see below) is handled by shell function func.

zle -Tr transformation removes the given transformation if it was present — and it's not an error if none was, so no stress.

zle -TL lists all transformations currently in operation.

Currently the only transformation is tc. It's used instead of outputting termcap codes to the terminal. When the transformation is in operation the shell function gets the termcap code that would have been output as its first argument, and if the operation required a numeric argument, that's passed as a second argument. The function should set the shell variable REPLY to the transformed termcap code. Typically this is used to produce some simply formatted version of the code and optional argument for debugging or testing. Note that this transformation is not applied to other non-printing characters like carriage returns and newlines 🎀.

widget [ -n num ] [ -f flag ] [ -Nw ] [ -K keymap ] args ... — invokes the specified widget. This can only be done when ZLE is active; normally that means you're inside a user-defined widget.

With the -n and -N options, the current numeric argument gets saved and then restored after the call to widget — -n num sets the numeric argument temporarily to num, while -N sets it to the default, i.e. as if there were none at all.

With the -K option, keymap is used as the current keymap while the widget executes, and the previous keymap gets restored when the widget exits. Slay. 🌈

...and lowkey that's the whole point: calling a widget this way doesn't normally set the special parameter WIDGET and its little friends, so the environment looks exactly like the top-level widget the user actually called is still the one running the show. But bestie, if you pass the -w option? Then WIDGET and the related parameters do get set to reflect the widget being executed by the zle call. Slay.

And normally, when a widget returns, the special parameter LASTWIDGET will point at it. Wanna block that? Just pass -f nolast. Iconic veto energy.

Any further arguments get passed straight to the widget — but heads up, standard argument handling is performed first, so if you've got a general argument list you gotta precede it with --. If it's a shell function, those args are passed down as positional parameters; for builtin widgets, what happens to them is entirely up to the widget in question. RN arguments are only handled by the incremental-search commands, the history-search-forward and -backward and the corresponding functions prefixed by vi-, and by universal-argument. And no error is flagged if the command doesn't use the arguments at all, or only uses some of them. Chill.

The return status reflects the success or failure of the operation the widget carried out, or — if it's a user-defined widget — the return status of the shell function. ✨

🚨 A non-zero return status causes the shell to beep when the widget exits, unless the BEEP option was unset or the widget was called via the zle command. So if a user-defined widget needs an immediate beep, it should call the beep widget directly. No cap.

🦋 ZLE WIDGETS 🦋

Okay so every single action in the editor is performed by widgets. That's it, that's the whole job description — a widget's job is simply to perform some small action. And plot twist: the ZLE commands that key sequences in keymaps are bound to are in fact widgets. Mind blown. Widgets can be user-defined or built in. 🫶

The standard widgets built into ZLE are listed in the section Standard Widgets below (iykyk). Other built-in widgets can be defined by other modules — see zshmodules(1).

Here's a cute detail: each built-in widget has two names — its normal canonical name, and the same name preceded by a .. The . name is special: it can't be rebound to a different widget. So even when the usual name gets redefined, the widget stays available. Main character refuses to be replaced. 💅

User-defined widgets are defined using zle -N, and implemented as shell functions. When the widget is executed, the corresponding shell function is executed, and it can perform editing (or other) actions. Oh, and a recommendation from the manual itself: user-defined widgets should not have names starting with ..

💜 USER-DEFINED WIDGETS 💜

So user-defined widgets are implemented as shell functions, which means they can execute any normal shell command. They can also run other widgets — built-in or user-defined — using the zle builtin command. But here's the thing: the standard input of the function is redirected from /dev/null so external commands can't unintentionally block ZLE by reading from the terminal. 🫶 However, read -k or read -q can be used to read characters, so you're not totally locked out.

Finally, they can examine and edit the ZLE buffer being edited by reading and setting the special parameters described below. This is where it gets good.

These special parameters are always available in widget functions, but they're not in any way special outside ZLE. If they have some normal value outside ZLE, that value is temporarily inaccessible — but it'll return when the widget function exits. These special parameters in fact have local scope, like parameters created in a function using local. 🎀

Inside completion widgets and traps called while ZLE is active, these parameters are available read-only.

⚠️ Note that the parameters appear as local to any ZLE widget in which they appear. Hence if you wanna override them, this needs to be done within a nested function:

widget-function() {
  # $WIDGET here refers to the special variable
  # that is local inside widget-function
  () {
     # This anonymous nested function allows WIDGET
     # to be used as a local variable.  The -h
     # removes the special status of the variable.
     local -h WIDGET
  }
}

Okay now let's meet the whole squad, one by one. 🌈

`BUFFER` (scalar)

The entire contents of the edit buffer. If it's written to, the cursor stays at the same offset — unless that would put it outside the buffer, in which case, well, it doesn't. Keep up. 😌

`BUFFERLINES` (integer)

The number of screen lines needed for the edit buffer currently displayed on screen (i.e. without any changes to the preceding parameters done after the last redisplay). Read-only. ✨

`CONTEXT` (scalar)

The context in which zle was called to read a line — read-only. One of these values:

start — the start of a command line (at prompt PS1).
cont — a continuation to a command line (at prompt PS2).
select — in a select loop (at prompt PS3).
vared — editing a variable in vared.

`CURSOR` (integer)

The offset of the cursor, within the edit buffer. This is in the range 0 to $#BUFFER, and is by definition equal to $#LBUFFER. Any attempts to move the cursor outside the buffer will just result in the cursor being moved to the appropriate end of the buffer. It said no and put itself where it belongs. 💅

`CUTBUFFER` (scalar)

The last item cut using one of the kill- commands; the string which the next yank would insert in the line. Later entries in the kill ring are in the array killring. And ngl this is a cute trick: the command zle copy-region-as-kill string can be used to set the text of the cut buffer from a shell function and cycle the kill ring in the same way as interactively killing text. Chef's kiss. 🔥

`HISTNO` (integer)

The current history number. Setting this has the same effect as moving up or down in the history to the corresponding history line. An attempt to set it is ignored if the line is not stored in the history. And don't get it twisted — this is not the same as the parameter HISTCMD, which always gives the number of the history line being added to the main shell's history. HISTNO refers to the line being retrieved within zle. Two different girlies, two different jobs. 🙈

`ISEARCHMATCH_ACTIVE` (integer), `ISEARCHMATCH_START` (integer), `ISEARCHMATCH_END` (integer)

ISEARCHMATCH_ACTIVE indicates whether a part of the BUFFER is currently matched by an incremental search pattern. ISEARCHMATCH_START and ISEARCHMATCH_END give the location of the matched part and are in the same units as CURSOR. They're only valid for reading when ISEARCHMATCH_ACTIVE is non-zero. ⭐

All parameters are read-only.

`KEYMAP` (scalar)

The name of the currently selected keymap; read-only.

`KEYS` (scalar)

The keys typed to invoke this widget, as a literal string; read-only.

`KEYS_QUEUED_COUNT` (integer)

The number of bytes pushed back to the input queue and therefore available for reading immediately before any I/O is done; read-only. See also PENDING; the two values are distinct. Don't mix them up bestie. 💀

`killring` (array)

The array of previously killed items, with the most recently killed first. This gives the items that would be retrieved by a yank-pop in the same order. But note, however, that the most recently killed item is in $CUTBUFFER; $killring shows the array of previous entries. Order matters, okay?

The default size for the kill ring is eight, however the length may be changed by normal array operations. Any empty string in the kill ring is ignored by the yank-pop command — hence the size of the array effectively sets the maximum length of the kill ring, while the number of non-zero strings gives the current length, both as seen by the user at the command line. Geometry. 🎀

`LASTABORTEDSEARCH` (scalar)

The last search string used by an interactive search that was aborted by the user (status 3 returned by the search widget). The quitter's last words, preserved forever. 😭

`LASTSEARCH` (scalar)

The last search string used by an interactive search; read-only. This is set even if the search failed (status 0, 1 or 2 returned by the search widget), but not if it was aborted by the user. So failed searches get remembered, rage-quits don't. Flaky but valid.

`LASTWIDGET` (scalar)

The name of the last widget that was executed; read-only.

`LBUFFER` (scalar)

The part of the buffer that lies to the left of the cursor position. If it's assigned to, only that part of the buffer is replaced, and the cursor remains between the new $LBUFFER and the old $RBUFFER. Seamless. ✨

`MARK` (integer)

Like CURSOR, but for the mark. With vi-mode operators that wait for a movement command to select a region of text, setting MARK allows the selection to extend in both directions from the initial cursor position. Both directions! Obsessed. 👑

`NUMERIC` (integer)

The numeric argument. If no numeric argument was given, this parameter is unset. When this is set inside a widget function, builtin widgets called with the zle builtin command will use the value assigned. If it's unset inside a widget function, builtin widgets called behave as if no numeric argument was given. Very "you get what you give" of it. 💖

`PENDING` (integer)

The number of bytes pending for input, i.e. the number of bytes which have already been typed and can immediately be read. On systems where the shell is not able to get this information, this parameter will always have a value of zero. Read-only. See also KEYS_QUEUED_COUNT; the two values are distinct. Again! Distinct! 🌸

`PREBUFFER` (scalar)

In a multi-line input at the secondary prompt, this read-only parameter contains the contents of the lines before the one the cursor is currently in. The lore before the line you're on. 📜

`PREDISPLAY` (scalar)

Text to be displayed before the start of the editable text buffer. This does not have to be a complete line; to display a complete line, a newline must be appended explicitly. The text is reset on each new invocation (but not recursive invocation) of zle. Important distinction, don't forget it. 🦋

`POSTDISPLAY` (scalar)

Text to be displayed after the end of the editable text buffer. This does not have to be a complete line; to display a complete line, a newline must be prepended explicitly. The text is reset on each new invocation (but not recursive invocation) of zle. Same energy, other side of the cursor. 💜

RBUFFER (scalar) — the chunk of the buffer sitting to the right of the cursor ✨. If you assign to it, only that part gets replaced, and the cursor just chills between the old $LBUFFER and the new $RBUFFER. No cap.
REGION_ACTIVE (integer) — tells you if the region is active rn. Assign 0 or 1 to deactivate / activate it. A value of 2 activates the region in line-wise mode, where the highlighted text only ever extends over whole lines — see Character Highlighting below 💅.
region_highlight (array) — each element is a string describing highlighting for any arbitrary region of the command line, and it kicks in the next time the command line gets redisplayed 🔥. You can highlight the non-editable parts of the command line in PREDISPLAY and POSTDISPLAY, but heads up: you need the P flag for character indexing to include PREDISPLAY.

Each string is made of these whitespace-separated parts:

Optionally, a P to signify that the start and end offsets that follow include any string set by the PREDISPLAY special parameter — you need this if the predisplay string itself is gonna be highlighted. Whitespace between the P and the start offset is optional.
A start offset, in the same units as CURSOR.
An end offset, in the same units as CURSOR.
A highlight specification in the same format used for contexts in the parameter zle_highlight — see the section Character Highlighting below; like standout or fg=red,bold, bestie.
Optionally, a string of the form memo=token. The token is everything between the = and the next whitespace, comma, NUL, or the end of the string. It's preserved verbatim but not parsed in any way.

Plugins may use this to identify array elements they added 🎀 — for example, a plugin might set token to its (the plugin's) name and then use region_highlight=( ${region_highlight:#*memo=token} ) to remove the array elements it added.

(That example uses the ${name:#pattern} array-grepping syntax described in the section Parameter Expansion in zshexpn(1).)

For example:

region_highlight=("P0 20 bold memo=foobar")

says the first twenty characters of the text, including any predisplay string, should be bold. Iconic 💖.

Note that the effect of region_highlight is not saved and disappears as soon as the line is accepted.

Note that zsh 5.8 and older do not support the memo=token field and may misparse the third (highlight specification) field when a memo is given. 💀

The final highlighting on the command line depends on both region_highlight and zle_highlight; see the section CHARACTER HIGHLIGHTING below for the deets.

registers (associative array) — the contents of each of the vi register buffers 🦋. These are typically set using vi-set-buffer followed by a delete, change or yank command.
SUFFIX_ACTIVE (integer)
SUFFIX_START (integer)
SUFFIX_END (integer) — SUFFIX_ACTIVE says whether an auto-removable completion suffix is currently active. SUFFIX_START and SUFFIX_END give the location of that suffix, in the same units as CURSOR 🌸. They're only valid for reading when SUFFIX_ACTIVE is non-zero.

All three parameters are read-only 🔒.

UNDO_CHANGE_NO (integer) — a number representing the state of the undo history. The only use for this is passing it as an argument to the undo widget so you can undo back to the recorded point. Read-only 📌.
UNDO_LIMIT_NO (integer) — a number corresponding to an existing change in the undo history; compare UNDO_CHANGE_NO. If you set this to a value greater than zero, the undo command won't let the line be undone beyond that change number. You can still use zle undo change in a widget to undo beyond that point — but in that case, it won't be possible to undo at all until UNDO_LIMIT_NO is reduced 😭. Set it to 0 to disable the limit.

A typical use of this variable in a widget function goes like this (note the extra function scope is required, bestie):

() {
  local UNDO_LIMIT_NO=$UNDO_CHANGE_NO
  # Perform some form of recursive edit.
}

WIDGET (scalar) — the name of the widget currently being executed; read-only 👑.
WIDGETFUNC (scalar) — the name of the shell function implementing a widget defined with either zle -N or zle -C. For zle -N, this is the second argument to the zle -N command that defined the widget, or the first argument if there was no second argument. For zle -C, it's the third argument to the zle -C command that defined the widget. Read-only 🫶.
WIDGETSTYLE (scalar) — describes the implementation behind the completion widget currently being executed; it's the second argument that followed zle -C when the widget was defined, i.e. the name of a builtin completion widget. For widgets defined with zle -N this is set to the empty string. Read-only ✨.
YANK_ACTIVE (integer)
YANK_START (integer)
YANK_END (integer) — YANK_ACTIVE says whether text has just been yanked (pasted) into the buffer 🍓. YANK_START and YANK_END give the location of the pasted text, in the same units as CURSOR. They're only valid for reading when YANK_ACTIVE is non-zero. They can also be assigned by widgets that insert text in a yank-like fashion — wrappers of bracketed-paste, for example. See also zle -f.

YANK_ACTIVE is read-only 🔒.

ZLE_RECURSIVE (integer) — usually zero, but it gets incremented inside any instance of recursive-edit, so it tells you the current recursion level 🌀.

ZLE_RECURSIVE is read-only.

ZLE_STATE (scalar) — holds a set of space-separated words describing the current zle state.

Currently, the states shown are the insert mode as set by the overwrite-mode or vi-replace widgets, and whether history commands will visit imported entries as controlled by the set-local-history widget 💫. The string contains insert if characters inserted on the command line move existing characters to the right, or overwrite if inserted characters overwrite existing ones. It contains localhistory if only local history commands get visited, or globalhistory if imported history commands get visited too.

The substrings are sorted alphabetically, so if you wanna test for two specific substrings in a future-proof way, you can match like this:

if [[ $ZLE_STATE == *globalhistory*insert* ]]; then ...; fi

🧚 Special Widgets 🧚

There are a few user-defined widgets that are special to the shell ✨. If they don't exist, no special action is taken. The environment they get is identical to that of any other editing widget — no VIP treatment, just vibes.

zle-isearch-exit — executed at the end of incremental search, right at the point where the isearch prompt is removed from the display. See zle-isearch-update for an example 👀.
zle-isearch-update — executed within incremental search when the display is about to be redrawn. You can generate extra output below the incremental search prompt by using zle -M inside the widget 🎀. For example:

zle-isearch-update() { zle -M "Line $HISTNO"; }
zle -N zle-isearch-update

Note that the line output by zle -M is not deleted on exit from incremental search 😭. You can do that from a zle-isearch-exit widget:

zle-isearch-exit() { zle -M ""; }
zle -N zle-isearch-exit

zle-line-pre-redraw — executed whenever the input line is about to be redrawn, giving you a lil opportunity to update the region_highlight array 💅.
zle-line-init — executed every time the line editor starts up to read a new line of input. This example puts the line editor into vi command mode on startup:

zle-line-init() { zle -K vicmd; }
zle -N zle-line-init

(The command inside the function sets the keymap directly; it's equivalent to zle vi-cmd-mode.)

zle-line-finish — similar to zle-line-init, but executed every time the line editor has finished reading a line of input 🌸.
zle-history-line-set — executed when the history line changes 📜.
zle-keymap-select — executed every time the keymap changes, i.e. every time the special parameter KEYMAP gets set to a different value, while the line editor is active 🔥. Initialising the keymap when the line editor starts does not cause the widget to be called.

The value $KEYMAP within the function reflects the new keymap. The old keymap is passed as the sole argument.

You can use this to detect switches between the vi command (vicmd) and insert (usually main) keymaps. iykyk 😌.

👑 STANDARD WIDGETS 👑

Here's the full list of all the standard widgets, plus their default bindings in emacs mode, vi command mode and vi insert mode (the emacs, vicmd and viins keymaps, respectively) 💖.

Note that cursor keys are bound to movement keys in all three keymaps — the shell assumes the cursor keys send the key sequences reported by the terminal-handling library (termcap or terminfo) 🖥️. The key sequences shown in the list are those based on the VT100, common on many modern terminals, but fr fr these are not necessarily bound. In the case of the viins keymap, the initial escape character of the sequences also serves to return to the vicmd keymap: whether that happens is determined by the KEYTIMEOUT parameter, see zshparam(1) ⏱️.

💫 Movement 💫

vi-backward-blank-word (unbound) (B) (unbound) — move backward one word, where a word is defined as a series of non-blank characters 🦋.
vi-backward-blank-word-end (unbound) (gE) (unbound) — bounce back to the end of the previous word, where a "word" is literally just a stretch of non-blank characters. no cap, blanks are the word boundaries here 💅
backward-char (^B ESC-[D) (unbound) (unbound) — slide back exactly one character. tiny steps, bestie 🐾
vi-backward-char (unbound) (^H h ^?) (ESC-[D) — one character back, but it will not hop up to the previous line. stays in its lane ✨
backward-word (ESC-B ESC-b) (unbound) (unbound) — zoom to the beginning of the previous word.
emacs-backward-word — same energy: beginning of the previous word. (no default bindings listed, she's just vibing 🎀)
vi-backward-word (unbound) (b) (unbound) — beginning of the previous word, but make it vi-style 😌
vi-backward-word-end (unbound) (ge) (unbound) — end of the previous word, vi-style. periodt.
beginning-of-line (^A) (unbound) (unbound) — hop to the start of the line. and if you're already at the start? it goes to the beginning of the previous line, if there is one. main character energy, always going further 🫶
vi-beginning-of-line — start of the line, but without changing lines. no field trips.
down-line (unbound) (unbound) (unbound) — move down a line in the buffer. that's it, that's the widget 💖
end-of-line (^E) (unbound) (unbound) — to the end of the line. if you're already there, it continues to the end of the next line, if any. slay, keep going ✨
vi-end-of-line (unbound) ($) (unbound) — end of the line. and if you hand this command an argument, the cursor gets moved to the end of the line (argument - 1) lines down. yes, the math is the math 🧮
vi-forward-blank-word (unbound) (W) (unbound) — forward one word, word = a run of non-blank characters.
vi-forward-blank-word-end (unbound) (E) (unbound) — to the end of the current word, or, if you're already chillin' at the end of the current word, to the end of the next one. again: word = series of non-blank characters 💅
forward-char (^F ESC-[C) (unbound) (unbound) — one character forward. baby steps 🌸
vi-forward-char (unbound) (space l) (ESC-[C) — one character forward, vi flavor.
vi-find-next-char (^X^F) (f) (unbound) — reads a character from your keyboard, then jumps to the next place that character shows up in the line. iconic little seeker 🔍
vi-find-next-char-skip (unbound) (t) (unbound) — reads a char from the keyboard and parks you just before the next occurrence of it in the line. so close, but not on it 🙈
vi-find-prev-char (unbound) (F) (unbound) — reads a char from the keyboard, jumps to the previous occurrence of it in the line.
vi-find-prev-char-skip (unbound) (T) (unbound) — reads a char and lands you just after the previous occurrence of it in the line.
vi-first-non-blank (unbound) (^) (unbound) — straight to the first non-blank character in the line. bye spaces 👋
vi-forward-word (unbound) (w) (unbound) — forward one word, vi-style.
forward-word (ESC-F ESC-f) (unbound) (unbound) — beginning of the next word. and the editor's whole idea of what counts as a "word" is decided by the WORDCHARS parameter, so that's the knob to turn 🎛️
emacs-forward-word — to the end of the next word. different destination, same vibe.
vi-forward-word-end (unbound) (e) (unbound) — end of the next word.
vi-goto-column (ESC-|) (|) (unbound) — jump to the column the numeric argument tells you. by the numbers 📏
vi-goto-mark (unbound) (`) (unbound) — teleport to the mark you specify. bookmark behavior fr fr 🔖
vi-goto-mark-line (unbound) (') (unbound) — to the beginning of the line that contains the mark you specify.
vi-repeat-find (unbound) (;) (unbound) — reruns your last vi-find command. encore, encore 👑
vi-rev-repeat-find (unbound) (,) (unbound) — reruns your last vi-find command, but in the opposite direction. plot twist 🌈
up-line (unbound) (unbound) (unbound) — move up a line in the buffer. ascending, literally 🦋

🕰️ History Control 🌸

beginning-of-buffer-or-history (ESC-<) (gg) (unbound) — to the beginning of the buffer, or, if you're already sitting there, to the first event in the history list. two-for-one 💖
beginning-of-line-hist — to the beginning of the line. but if you're already at the beginning of the buffer, it moves to the previous history line. sneaky but slay.
beginning-of-history — jumps to the first event in the history list. back to the very first lore drop 📜
down-line-or-history (^N ESC-[B) (j) (ESC-[B) — down a line in the buffer, or, if you're already on the bottom line, to the next event in the history list.
vi-down-line-or-history (unbound) (+) (unbound) — down a line in the buffer, or, if you're on the bottom line, to the next history event. then it moves to the first non-blank character on the line. whole little routine ✨
down-line-or-search — down a line in the buffer, or, if you're already on the bottom line, search forward in the history for a line that begins with the first word in the buffer.

if it's called from a function by the zle command with arguments, then the first argument is used as the string to search for, instead of the first word in the buffer. so you get to choose the quest 🗺️

down-history (unbound) (^N) (unbound) — next event in the history list. onward 🚀
history-beginning-search-backward — searches backward through history for a line beginning with the current line up to the cursor. and it leaves the cursor exactly where it originally was, because she's polite like that 🎀
end-of-buffer-or-history (ESC->) (unbound) (unbound) — to the end of the buffer, or, if you're already there, to the last event in the history list.
end-of-line-hist — to the end of the line. if you're already at the end of the buffer, it goes to the next history line.
end-of-history — to the last event in the history list. the finale 👑
vi-fetch-history (unbound) (G) (unbound) — fetch the history line given by the numeric argument. it defaults to the current history line (i.e. the one that isn't history yet). iykyk 😌
history-incremental-search-backward (^R ^Xr) (unbound) (unbound) — incremental backward search for a string you type. it's case-insensitive if the search string has no uppercase letters and no numeric argument was given. the string can start with ^ to anchor the search to the beginning of the line. 🔍

when it's called from a user-defined function it returns these statuses: 0 if the search succeeded; 1 if the search failed; 2 if the search term was a bad pattern; 3 if the search was aborted by the send-break command. receipts, always 🧾

a restricted set of editing functions is available in the mini-buffer. keys get looked up in the special isearch keymap, and if they're not found there, in the main keymap (note that by default the isearch keymap is empty). an interrupt signal, as defined by the stty setting, will stop the search and go back to the original line. an undefined key does exactly the same thing. 💀

also important: the following always do the same task inside incremental searches and cannot be replaced by user defined widgets, and the set of functions cannot be extended. immutable. no edits. 🚫

the supported functions are:

accept-and-hold
accept-and-infer-next-history
accept-line
accept-line-and-down-history — do the usual function after you exit incremental search. the command line displayed is executed. 💅
backward-delete-char
vi-backward-delete-char — back up one place in the search history. if the search has been repeated, this does not immediately erase a character in the minibuffer.
accept-search — exit incremental search, keeping the command line but doing nothing else. note this function is not bound by default and has no effect outside incremental search. 🙈
backward-delete-word
backward-kill-word
vi-backward-kill-word — back up one character in the minibuffer; and if multiple searches have happened since that character was inserted, the search history gets rewound to just before the character was entered. so basically it repeats backward-delete-char. cute recursion 🌀
clear-screen — clears the screen and stays in incremental search mode.
history-incremental-search-backward — finds the next occurrence of whatever's in the mini-buffer. if the mini-buffer is empty, the most recent previously used search string comes back. she remembers 💭
history-incremental-search-forward — flips the direction of the search.
magic-space — inserts a non-magical space. the plain kind ✨
quoted-insert
vi-quoted-insert — quote the character that's going into the minibuffer.
redisplay — redisplay the command line, staying in incremental search mode.
vi-cmd-mode — picks the vicmd keymap; the main keymap (insert mode) gets selected initially.

on top of that, the modifications made while in vi insert mode get merged into a single undo event. one undo, all of it, obsessed 🫶

vi-repeat-search
vi-rev-repeat-search — repeat the search. the direction is shown right there in the mini-buffer. arrows, basically ➡️⬅️

any character that isn't bound to one of the functions above, or to self-insert or self-insert-unmeta, will make the mode exit. then that character is looked up and executed in whatever keymap is in effect at that point. eviction notice 🚪

and when it's called from a widget function by the zle command, the incremental search commands can take a string argument. that's treated as a string of keys, exactly like arguments to the bindkey command, and used as the initial input for the command. any characters in the string that incremental search doesn't use just get silently ignored. for example:

zle history-incremental-search-backward forceps

searches backwards for forceps and leaves the minibuffer containing the string forceps. 🩺✨

history-incremental-search-forward (^S ^Xs) (unbound) (unbound) — incremental forward search for a string. case-insensitive if the search string has no uppercase letters and no numeric argument was given. the string may begin with ^ to anchor the search to the beginning of the line. the functions available in the mini-buffer are exactly the same as for history-incremental-search-backward. same menu, opposite direction 💖

🦋 `history-incremental-pattern-search-backward` / `history-incremental-pattern-search-forward`

Okay so these two are basically the -pattern-less versions but with ✨pattern matching✨ turned on. The search string you type is treated as a pattern — respecting the current settings of the various options affecting pattern matching, no cap. Peep FILENAME GENERATION in zshexpn(1) for the whole pattern saga.

If no numeric argument was given, lowercase letters in the search string may match uppercase letters in the history (yes bestie, case-insensitive vibes). And the string may begin with ^ to anchor the search to the beginning of the line 🎯

The prompt changes to indicate an invalid pattern — which, lowkey, may simply mean the pattern is not yet complete. Don't panic 🙈

Note that only non-overlapping matches are reported, so an expression with wildcards may return fewer matches on a line than are visible by inspection. It's giving "trust the process", not a bug.

🔎 `history-search-backward` — emacs `ESC-P` `ESC-p` · vi cmd `unbound` · vi ins `unbound`

Search backward in the history for a line beginning with the first word in the buffer. Obsessed, honestly.

If called from a function by the zle command with arguments, the first argument is taken as the string for which to search, rather than the first word in the buffer 💅

🌸 `vi-history-search-backward` — emacs `unbound` · vi cmd `/` · vi ins `unbound`

Search backward in the history for a specified string. The string may begin with ^ to anchor the search to the beginning of the line.

A restricted set of editing functions is available in the mini-buffer. An interrupt signal, as defined by the stty setting, will stop the search. The functions available in the mini-buffer are:

accept-line
backward-delete-char
vi-backward-delete-char
backward-kill-word
vi-backward-kill-word
clear-screen
redisplay
quoted-insert
vi-quoted-insert

vi-cmd-mode is treated the same as accept-line, and magic-space is treated as a space. Any other character that is not bound to self-insert or self-insert-unmeta will beep and be ignored 🐝 If the function is called from vi command mode, the bindings of the current insert mode will be used.

If called from a function by the zle command with arguments, the first argument is taken as the string for which to search, rather than the first word in the buffer.

🔎 `history-search-forward` — emacs `ESC-N` `ESC-n` · vi cmd `unbound` · vi ins `unbound`

Search forward in the history for a line beginning with the first word in the buffer. Same energy as its backward sibling, just pointing the other way 🫶

If called from a function by the zle command with arguments, the first argument is taken as the string for which to search, rather than the first word in the buffer.

🌸 `vi-history-search-forward` — emacs `unbound` · vi cmd `?` · vi ins `unbound`

Search forward in the history for a specified string. The string may begin with ^ to anchor the search to the beginning of the line.

The functions available in the mini-buffer are the same as for vi-history-search-backward. Argument handling is also the same as for that command. Reuse is the moment, periodt 💅

🧚 `infer-next-history` — emacs `^X^N` · vi cmd `unbound` · vi ins `unbound`

Search in the history list for a line matching the current one and fetch the event following it. It's giving main character energy: find your twin, then take the next step 🔥

🌟 `insert-last-word` — emacs `ESC-_` `ESC-.` · vi cmd `unbound` · vi ins `unbound`

Insert the last word from the previous history event at the cursor position.

If a positive numeric argument is given, insert that word from the end of the previous history event.
If the argument is zero or negative, insert that word from the left (zero inserts the previous command word).

Repeating this command replaces the word just inserted with the last word from the history event prior to the one just used; numeric arguments can be used in the same way to pick a word from that event 😭 (the way this thing just keeps walking backwards through history is iconic).

When called from a shell function invoked from a user-defined widget, the command can take one to three arguments:

The first argument specifies a history offset which applies to successive calls to this widget: if it is -1, the default behaviour is used; if it is 1, successive calls will move forwards through the history. The value 0 can be used to indicate that the history line examined by the previous execution of the command will be reexamined.
If two arguments are given, the second specifies the word on the command line in normal array index notation (as a more natural alternative to the numeric argument). Hence 1 is the first word, and -1 (the default) is the last word.
If a third argument is given, its value is ignored, but it is used to signify that the history offset is relative to the current history line, rather than the one remembered after the previous invocations of insert-last-word.

⚠️ Note that negative numbers should be preceded by a -- argument to avoid confusing them with options. The classic little trap 🙈

For example, the default behaviour of the command corresponds to

zle insert-last-word -- -1 -1

while the command

zle insert-last-word -- -1 1 -

always copies the first word of the line in the history immediately before the line being edited. This has the side effect that later invocations of the widget will be relative to that line. Sneaky but slay ✨

🔁 `vi-repeat-search` — emacs `unbound` · vi cmd `n` · vi ins `unbound`

Repeat the last vi history search. Again, again, again 🔂

🔁 `vi-rev-repeat-search` — emacs `unbound` · vi cmd `N` · vi ins `unbound`

Repeat the last vi history search, but in reverse. Same search, opposite direction, literally 💀

⬆️ `up-line-or-history` — emacs `^P` `ESC-[A` · vi cmd `k` · vi ins `ESC-[A`

Move up a line in the buffer, or — if you're already at the top line — move to the previous event in the history list. Two-for-one behaviour, we love a multitasker 👑

🌸 `vi-up-line-or-history` — emacs `unbound` · vi cmd `-` · vi ins `unbound`

Move up a line in the buffer, or if already at the top line, move to the previous event in the history list. Then move to the first non-blank character on the line. Extra step, extra precision 🎯

⬆️ `up-line-or-search`

Move up a line in the buffer, or if already at the top line, search backward in the history for a line beginning with the first word in the buffer.

If called from a function by the zle command with arguments, the first argument is taken as the string for which to search, rather than the first word in the buffer 🫶

⬆️ `up-history` — emacs `unbound` · vi cmd `^P` · vi ins `unbound`

Move to the previous event in the history list. Simple. Clean. No notes 💅

🔍 `history-beginning-search-forward`

Search forward in the history for a line beginning with the current line up to the cursor. This leaves the cursor in its original position — so your cursor stays exactly where it was, bestie, no jumpscares 🙈

🎀 `set-local-history`

By default, history movement commands visit the imported lines as well as the local lines. This widget lets you toggle this on and off, or set it with the numeric argument. 0 for both local and imported lines, and nonzero for only local lines. Your little history filter switch 🌈

💅 Modifying Text 💅

Okay this section is where we actually change things. Destructive girlies, gather round 🔥

🌸 `vi-add-eol` — emacs `unbound` · vi cmd `A` · vi ins `unbound`

Move to the end of the line and enter insert mode. Simple slay.

🌸 `vi-add-next` — emacs `unbound` · vi cmd `a` · vi ins `unbound`

Enter insert mode after the current cursor position, without changing lines. Right where you're at, just one to the right 💅

⌫ `backward-delete-char` — emacs `^H` `^?` · vi cmd `unbound` · vi ins `unbound`

Delete the character behind the cursor. Bye bestie 👋

🌸 `vi-backward-delete-char` — emacs `unbound` · vi cmd `X` · vi ins `^H`

Delete the character behind the cursor, without changing lines. If in insert mode, this won't delete past the point where insert mode was last entered — there's a boundary, and it respects it 🚧

⌫ `backward-delete-word`

Delete the word behind the cursor. Whole word, gone, no crumbs.

✂️ `backward-kill-line`

Kill from the beginning of the line to the cursor position. Very "cut to the chase", literally.

✂️ `backward-kill-word` — emacs `^W` `ESC-^H` `ESC-^?` · vi cmd `unbound` · vi ins `unbound`

Kill the word behind the cursor. Say it with your chest 🗣️

🌸 `vi-backward-kill-word` — emacs `unbound` · vi cmd `unbound` · vi ins `^W`

Kill the word behind the cursor, without going past the point where insert mode was last entered. Respect the boundary, always 🫶

🅰️ `capitalize-word` — emacs `ESC-C` `ESC-c` · vi cmd `unbound` · vi ins `unbound`

Capitalize the current word and move past it. Glow-up arc for your word ✨

🌸 `vi-change` — emacs `unbound` · vi cmd `c` · vi ins `unbound`

Read a movement command from the keyboard, and kill from the cursor position to the endpoint of the movement. Then enter insert mode. If the command is vi-change, change the current line.

For compatibility with vi, if the command is vi-forward-word or vi-forward-blank-word, the whitespace after the word is not included. If you prefer the more consistent behaviour with the whitespace included, use the following key binding:

bindkey -a -s cw dwi

iykyk 😌

🌸 `vi-change-eol` — emacs `unbound` · vi cmd `C` · vi ins `unbound`

Kill to the end of the line and enter insert mode. Clean sweep to the edge 🧹

🌸 `vi-change-whole-line` — emacs `unbound` · vi cmd `S` · vi ins `unbound`

Kill the current line and enter insert mode. Total reset, fresh start, main character reboot 🔥

📋 `copy-region-as-kill` — emacs `ESC-W` `ESC-w` · vi cmd `unbound` · vi ins `unbound`

Copy the area from the cursor to the mark to the kill buffer.

If called from a ZLE widget function in the form zle copy-region-as-kill string then string will be taken as the text to copy to the kill buffer. The cursor, the mark and the text on the command line are not used in this case. So you can just hand it text directly, no cap 💅

🗂️ `copy-prev-word` — emacs `ESC-^_` · vi cmd `unbound` · vi ins `unbound`

Duplicate the word to the left of the cursor. Copy-paste but make it effortless 🫶

🗂️ `copy-prev-shell-word`

Like copy-prev-word, but the word is found by using shell parsing, whereas copy-prev-word looks for blanks. This makes a difference when the word is quoted and contains spaces. So if your word is being extra about it, this one gets it 🎀

🌸 `vi-delete` — emacs `unbound` · vi cmd `d` · vi ins `unbound`

Read a movement command from the keyboard, and kill from the cursor position to the endpoint of the movement. If the command is vi-delete, kill the current line. Combo move, very iconic 👑

⌫ `delete-char`

Delete the character under the cursor. Right there. Gone. 💀

🌸 `vi-delete-char` — emacs `unbound` · vi cmd `x` · vi ins `unbound`

Delete the character under the cursor, without going past the end of the line. Knows when to stop, unlike some of us 😭

⌫ `delete-word`

Delete the current word. Just the one. Precise.

🔡 `down-case-word` — emacs `ESC-L` `ESC-l` · vi cmd `unbound` · vi ins `unbound`

Convert the current word to all lowercase and move past it. Quiet-luxury typography moment 🌸

🌸 `vi-down-case` — emacs `unbound` · vi cmd `gu` · vi ins `unbound`

Read a movement command from the keyboard, and convert all characters from the cursor position to the endpoint of the movement to lowercase. If the movement command is vi-down-case, swap the case of all characters on the current line. Surprise mechanic, ilysm 🔄

✂️ `kill-word` — emacs `ESC-D` `ESC-d` · vi cmd `unbound` · vi ins `unbound`

Kill the current word. That's it, that's the widget 🔥

🎀 `gosmacs-transpose-chars`

Exchange the two characters behind the cursor. Little swap, retro name, love that journey for it ✨

🌸 `vi-indent` — emacs `unbound` · vi cmd `>` · vi ins `unbound`

Indent a number of lines. Nested aesthetics, ltr 💅

vi-insert — keys (unbound) (i) (unbound) — bestie we're going into insert mode ✨
vi-insert-bol — keys (unbound) (I) (unbound) — jump to the first non-blank character on the line and slide into insert mode, two birds one stone 💅
vi-join — keys (^X^J) (J) (unbound) — smoosh the current line together with the next one 🫶
kill-line — keys (^K) (unbound) (unbound) — kill everything from the cursor to the end of the line, no cap. And if you're already chillin' at the end of the line? It kills the newline character instead 💀
vi-kill-line — keys (unbound) (unbound) (^U) — kill from the cursor all the way back to wherever insert mode was last entered, iconic rewind energy ⏪
vi-kill-eol — keys (unbound) (D) (unbound) — kill from the cursor to the end of the line, periodt 🎀
kill-region — kill from the cursor to the mark 🎯
kill-buffer — keys (^X^K) (unbound) (unbound) — kill the entire buffer. like, all of it. main character destruction 🔥
kill-whole-line — keys (^U) (unbound) (unbound) — kill the current line, the whole line, nothing but the line ✨
vi-match-bracket — keys (^X^B) (%) (unbound) — bounce to the bracket character (one of {}, () or []) that matches the one under the cursor. and if the cursor isn't sitting on a bracket? it moves forward — without going past the end of the line — until it finds one, then goes to its matching bracket. lowkey detective work 🔍
vi-open-line-above — keys (unbound) (O) (unbound) — open a line above the cursor and enter insert mode 🦋
vi-open-line-below — keys (unbound) (o) (unbound) — open a line below the cursor and enter insert mode 🌸
vi-oper-swap-case — keys (unbound) (g~) (unbound) — reads a movement command straight from the keyboard, then swaps the case of every character from the cursor position to wherever that movement ends up. and if the movement command is vi-oper-swap-case? it swaps the case of all characters on the current line, we love a self-referential moment 💅
overwrite-mode — keys (^X^O) (unbound) (unbound) — toggle between overwrite mode and insert mode, flip flopping like your fave 🔄
vi-put-before — keys (unbound) (P) (unbound) — insert the contents of the kill buffer before the cursor. if the kill buffer holds a sequence of lines (as opposed to characters), it pastes it above the current line 🫶
vi-put-after — keys (unbound) (p) (unbound) — insert the contents of the kill buffer after the cursor. if the kill buffer holds a sequence of lines (as opposed to characters), it pastes it below the current line 🫶
put-replace-selection — keys (unbound) (unbound) (unbound) — replace the contents of the current region or selection with the contents of the kill buffer. and if the kill buffer holds a sequence of lines (as opposed to characters), the current line gets split by the pasted lines. no thoughts, just vibes ✨
quoted-insert — keys (^V) (unbound) (unbound) — insert the next character you type into the buffer literally. warning bestie: an interrupt character will not be inserted 🚨
vi-quoted-insert — keys (unbound) (unbound) (^Q ^V) — displays a ^ at the cursor position, then inserts the next character you type into the buffer literally. same deal: an interrupt character will not be inserted 🙈
quote-line — keys (ESC-') (unbound) (unbound) — quote the current line, meaning it puts a ' character at the beginning and the end, and converts all ' characters to '\'' 🎀
quote-region — keys (ESC-") (unbound) (unbound) — quote the region from the cursor to the mark 💖
vi-replace — keys (unbound) (R) (unbound) — enter overwrite mode 👑
vi-repeat-change — keys (unbound) (.) (unbound) — repeat the last vi mode text modification. if a count was used with that modification, it's remembered. if you give a count to this command, it overrides the remembered count and gets remembered for future uses of this command. the cut buffer specification is remembered in the same way. the way this remembers everything?? memory of an elephant fr fr 🐘
vi-replace-chars — keys (unbound) (r) (unbound) — replace the character under the cursor with a character read from the keyboard ⌨️
self-insert — keys (printable characters) (unbound) (printable characters and some control characters) — insert a character into the buffer at the cursor position. the moment itself 💫
self-insert-unmeta — keys (ESC-^I ESC-^J ESC-^M) (unbound) (unbound) — insert a character into the buffer after stripping the meta bit and converting ^M to ^J 🧚
vi-substitute — keys (unbound) (s) (unbound) — substitute the next character(s) 🔁
vi-swap-case — keys (unbound) (~) (unbound) — swap the case of the character under the cursor and move past it ✨
transpose-chars — keys (^T) (unbound) (unbound) — exchange the two characters to the left of the cursor if you're at the end of the line, otherwise exchange the character under the cursor with the character to the left 🤝
transpose-words — keys (ESC-T ESC-t) (unbound) (unbound) — exchange the current word with the one before it. with a positive numeric argument N, the word around the cursor (or following it, if the cursor is between words) is transposed with the preceding N words, and the cursor ends up at the end of the resulting group of words. with a negative numeric argument -N, it's the same as using a positive argument N — except the original cursor position is kept, no matter how the words get rearranged. chaotic but principled 🌪️
vi-unindent — keys (unbound) (<) (unbound) — unindent a number of lines 📉
vi-up-case — keys (unbound) (gU) (unbound) — read a movement command from the keyboard, and convert all characters from the cursor position to the endpoint of the movement to lowercase. and if the movement command is vi-up-case, swap the case of all characters on the current line 👑 (yes, that's exactly what it says, keep reading, it's giving "the docs said what they said" 💀)
up-case-word — keys (ESC-U ESC-u) (unbound) (unbound) — convert the current word to all caps and move past it 📢
yank — keys (^Y) (unbound) (unbound) — insert the contents of the kill buffer at the cursor position 💖
yank-pop — keys (ESC-y) (unbound) (unbound) — remove the text just yanked, rotate the kill-ring (that's the history of previously killed text, iykyk) and yank the new top. only works following yank, vi-put-before, vi-put-after or yank-pop ⚠️
vi-yank — keys (unbound) (y) (unbound) — read a movement command from the keyboard, and copy the region from the cursor position to the endpoint of the movement into the kill buffer. if the command is vi-yank, copy the current line 📋
vi-yank-whole-line — keys (unbound) (Y) (unbound) — copy the current line into the kill buffer 🎀
vi-yank-eol — copy the region from the cursor position to the end of the line into the kill buffer. arguably, this is what Y should do in vi, but it isn't what it actually does 🙈 (the audacity, honestly)

✨ Arguments ✨

okay so this is the whole how many times / which direction department, and it's giving math class but make it cute 🧮

digit-argument — keys (ESC-0..ESC-9) (1-9) (unbound) — start a new numeric argument, or add to the current one. see also vi-digit-or-beginning-of-line. this only works if it's bound to a key sequence ending in a decimal digit. pro tip: inside a widget function, a call to this function treats the last key of the key sequence that called the widget as the digit 💅
neg-argument — keys (ESC--) (unbound) (unbound) — changes the sign of the following argument. flip it 🔄
universal-argument — multiply the argument of the next command by 4. alternatively, if this command is followed by an integer (positive or negative), use that as the argument for the next command. so yeah, digits can't be repeated using this command, noted 📝. for example: if this command occurs twice, followed immediately by forward-char, you move forward sixteen spaces. if instead it's followed by -2, then forward-char, you move backward two spaces. and inside a widget function, if you pass it an argument, i.e. zle universal-argument num, the numeric argument gets set to num — which is equivalent to NUMERIC=num ✨
argument-base — use the existing numeric argument as a numeric base, which must be in the range 2 to 36 inclusive. after that, using digit-argument and universal-argument inputs a new numeric argument in that base. the usual hexadecimal convention applies: the letter a or A corresponds to 10, and so on. arguments in bases that need digits from 10 upwards are way more conveniently input with universal-argument, since ESC-a etc. aren't usually bound to digit-argument. this function can be used with a command argument inside a user-defined widget — the following code sets the base to 16 and lets the user input a hexadecimal argument until a key out of the digit range is typed:

zle argument-base 16
zle universal-argument

Completion ✨

accept-and-menu-complete — in a menu completion, insert the current completion into the buffer, and advance to the next possible completion 🌈
complete-word — attempt completion on the current word 🎯
delete-char-or-list — keys (^D) (unbound) (unbound) — delete the character under the cursor. but if the cursor is at the end of the line, list possible completions for the current word instead. dual purpose icon 💅
expand-cmd-path — expand the current command to its full pathname 🛣️
expand-or-complete — keys (TAB) (unbound) (TAB) — attempt shell expansion on the current word, and if that fails, attempt completion. the try-again energy 🫶
expand-or-complete-prefix — attempt shell expansion on the current word up to the cursor ✂️
expand-history — keys (ESC-space ESC-!) (unbound) (unbound) — perform history expansion on the edit buffer 📜
expand-word — keys (^X*) (unbound) (unbound) — attempt shell expansion on the current word 💫
list-choices — keys (ESC-^D) (^D =) (^D) — list possible completions for the current word 📋
list-expand — keys (^Xg ^XG) (^G) (^G) — list the expansion of the current word 🔍
magic-space — perform history expansion and insert a space into the buffer. this is intended to be bound to space ✨ (yes, the space bar. magic fr)
menu-complete — like complete-word, except that menu completion is used. see the MENU_COMPLETE option 👑
menu-expand-or-complete — like expand-or-complete, except that menu completion is used 🎀
reverse-menu-complete — perform menu completion, like menu-complete, except that if a menu completion is already in progress, move to the previous completion rather than the next one ⏪
end-of-list — when a previous completion displayed a list below the prompt, this widget can be used to move the prompt below the list 🦋

Miscellaneous 🌸

accept-and-hold — keys (ESC-A ESC-a) (unbound) (unbound) — push the contents of the buffer on the buffer stack and execute it 🫶
accept-and-infer-next-history — execute the contents of the buffer. then search the history list for a line matching the current one and push the event following onto the buffer stack 🔮

`accept-line` — `(^J ^M)` `(^J ^M)` `(^J ^M)`

Finish editing the buffer, bestie. Normally this is the moment your line gets executed as a shell command. Yes, that's just the Return key being iconic 💅

`accept-line-and-down-history` — `(^O)` `(unbound)` `(unbound)`

Execute the current line, and push the next history event on the buffer stack. Run it, then your next command is already waiting for you like a true main character ✨

`auto-suffix-remove`

If the previous action added a suffix (space, slash, etc.) to the word on the command line, remove it. Otherwise do nothing — no drama. Removing the suffix ends any active menu completion or menu selection.

This widget is intended to be called from user-defined widgets to enforce a desired suffix-removal behavior 🎀

`auto-suffix-retain`

Same vibe check as above, opposite ending: if the previous action added a suffix (space, slash, etc.) to the word on the command line, force it to be preserved. Otherwise do nothing. Retaining the suffix also ends any active menu completion or menu selection.

This widget is intended to be called from user-defined widgets to enforce a desired suffix-preservation behavior 🫶

`beep`

Beep, unless the BEEP option is unset. That's it. That's the widget 🔔

`bracketed-paste` — `(^[[200~)` `(^[[200~)` `(^[[200~)`

This widget is invoked when text is pasted to the terminal emulator. It is not intended to be bound to actual keys — instead it's for the special sequence generated by the terminal emulator when text is pasted, iykyk.

When invoked interactively, the pasted text is inserted to the buffer and placed in the cutbuffer. If a numeric argument is given, shell quoting will be applied to the pasted text before it is inserted.

When a named buffer is specified with vi-set-buffer ("x), the pasted text is stored in that named buffer but not inserted.

When called from a widget function as bracketed-paste name, the pasted text is assigned to the variable name and no other processing is done.

See also the zle_bracketed_paste parameter 🌸

`vi-cmd-mode` — `(^X^V)` `(unbound)` `(^[)`

Enter command mode — that is, select the vicmd keymap. And yes, this is bound by default in emacs mode. Not me pointing that out 💀

`vi-caps-lock-panic`

Hang until any lowercase key is pressed. This is for vi users without the mental capacity to keep track of their caps lock key (like the author). Respect for the self-callout, honestly 🙈

`clear-screen` — `(^L ESC-^L)` `(^L)` `(^L)`

Clear the screen and redraw the prompt. Fresh canvas energy ✨

`deactivate-region`

Make the current region inactive. This disables vim-style visual selection mode if it is active 🦋

`describe-key-briefly`

Reads a key sequence, then prints the function bound to that sequence. Like a little fortune teller for your keyboard 🔮

`exchange-point-and-mark` — `(^X^X)` `(unbound)` `(unbound)`

Exchange the cursor position (point) with the position of the mark. Unless a negative numeric argument is given, the region between point and mark is activated so that it can be highlighted. If a zero numeric argument is given, the region is activated but point and mark are not swapped. Sneaky little detail, don't sleep on it 👑

`execute-named-cmd` — `(ESC-x)` `(:)` `(unbound)`

Read the name of an editor command and execute it. Heads up: aliasing this widget with zle -A or replacing it with zle -N has no effect when interpreting key bindings — but zle execute-named-cmd will invoke such an alias or replacement. Pick your lane, bestie 💅

A restricted set of editing functions is available in the mini-buffer. Keys are looked up in the special command keymap, and if not found there, in the main keymap. An interrupt signal, as defined by the stty setting, will abort the function. Note that the following always perform the same task within the executed-named-cmd environment and cannot be replaced by user defined widgets, nor can the set of functions be extended. The allowed functions are:

backward-delete-char
vi-backward-delete-char
clear-screen
redisplay
quoted-insert
vi-quoted-insert
backward-kill-word
vi-backward-kill-word
kill-whole-line
vi-kill-line
backward-kill-line
list-choices
delete-char-or-list
complete-word
accept-line
expand-or-complete
expand-or-complete-prefix

kill-region kills the last word, and vi-cmd-mode is treated the same as accept-line. The space and tab characters, if not bound to one of these functions, will complete the name and then list the possibilities if the AUTO_LIST option is set. Any other character that is not bound to self-insert or self-insert-unmeta will beep and be ignored. The bindings of the current insert mode will be used.

Currently this command may not be redefined or called by name 😭

`execute-last-named-cmd` — `(ESC-z)` `(unbound)` `(unbound)`

Redo the last function executed with execute-named-cmd. Like execute-named-cmd, this command may not be redefined — but it may be called by name. Character development fr fr 🌈

`get-line` — `(ESC-G ESC-g)` `(unbound)` `(unbound)`

Pop the top line off the buffer stack and insert it at the cursor position. Little snack, delivered fresh 🍓

`pound-insert` — `(unbound)` `(#)` `(unbound)`

If there is no # character at the beginning of the buffer, add one to the beginning of each line. If there is one, remove a # from each line that has one. In either case, accept the current line. The INTERACTIVE_COMMENTS option must be set for this to have any usefulness. Comment out the whole vibe, periodt ✨

`vi-pound-insert`

If there is no # character at the beginning of the current line, add one. If there is one, remove it. The INTERACTIVE_COMMENTS option must be set for this to have any usefulness. One line only, no over-committing 💅

`push-input`

Push the entire current multiline construct onto the buffer stack and return to the top-level (PS1) prompt. If the current parser construct is only a single line, this is exactly like push-line. Next time the editor starts up or is popped with get-line, the construct will be popped off the top of the buffer stack and loaded into the editing buffer 🎀

`push-line` — `(^Q ESC-Q ESC-q)` `(unbound)` `(unbound)`

Push the current buffer onto the buffer stack and clear the buffer. Next time the editor starts up, the buffer will be popped off the top of the buffer stack and loaded into the editing buffer. Stash it, don't trash it 🦋

`push-line-or-edit`

At the top-level (PS1) prompt, equivalent to push-line. At a secondary (PS2) prompt, move the entire current multiline construct into the editor buffer. That latter one is equivalent to push-input followed by get-line. Two modes, one widget, main character energy 👑

`read-command`

Only useful from a user-defined widget. A keystroke is read just as in normal operation, but instead of the command being executed, the name of the command that would be executed is stored in the shell parameter REPLY. This can be used as the argument of a future zle command. If the key sequence is not bound, status 1 is returned; typically, however, REPLY is set to undefined-key to indicate a useless key sequence 💀

`recursive-edit`

Only useful from a user-defined widget. At this point in the function, the editor regains control until one of the standard widgets which would normally cause zle to exit (typically an accept-line caused by hitting the return key) is executed. Instead, control returns to the user-defined widget. The status returned is non-zero if the return was caused by an error, but the function still continues executing and hence may tidy up. This makes it safe for the user-defined widget to alter the command line or key bindings temporarily 🫶

The following widget, caps-lock, serves as an example.

self-insert-ucase() {
  LBUFFER+=${(U)KEYS[-1]}
}

integer stat

zle -N self-insert self-insert-ucase
zle -A caps-lock save-caps-lock
zle -A accept-line caps-lock

zle recursive-edit
stat=$?

zle -A .self-insert self-insert
zle -A save-caps-lock caps-lock
zle -D save-caps-lock

(( stat )) && zle send-break

return $stat

This causes typed letters to be inserted capitalised until either accept-line (i.e. typically the return key) is typed or the caps-lock widget is invoked again; the latter is handled by saving the old definition of caps-lock as save-caps-lock and then rebinding it to invoke accept-line. Note that an error from the recursive edit is detected as a non-zero return status and propagated by using the send-break widget 🔥

`redisplay` — `(unbound)` `(^R)` `(^R)`

Redisplays the edit buffer. A little refresh for the timeline 💅

`reset-prompt` — `(unbound)` `(unbound)` `(unbound)`

Force the prompts on both the left and right of the screen to be re-expanded, then redisplay the edit buffer. This reflects changes both to the prompt variables themselves and changes in the expansion of the values (for example, changes in time or directory, or changes to the value of variables referred to by the prompt).

Otherwise, the prompt is only expanded each time zle starts, and when the display has been interrupted by output from another part of the shell (such as a job notification) which causes the command line to be reprinted.

reset-prompt doesn't alter the special parameter LASTWIDGET. Leave that one alone, she's booked ✨

`send-break` — `(^G ESC-^G)` `(unbound)` `(unbound)`

Abort the current editor function, e.g. execute-named-command, or the editor itself, e.g. if you are in vared. Otherwise abort the parsing of the current line; in this case the aborted line is available in the shell variable ZLE_LINE_ABORTED. If the editor is aborted from within vared, the variable ZLE_VARED_ABORTED is set. Emergency exit, but make it chic 😭

`run-help` — `(ESC-H ESC-h)` `(unbound)` `(unbound)`

Push the buffer onto the buffer stack, and execute the command run-help cmd, where cmd is the current command. run-help is normally aliased to man. Asking for help is self-care, bestie 🎀

`vi-set-buffer` — `(unbound)` `(")` `(unbound)`

Specify a buffer to be used in the following command. There are 37 buffers that can be specified: the 26 named buffers "a to "z, the yank buffer "0, the nine queued buffers "1 to "9 and the black hole buffer "_. The named buffers can also be specified as "A to "Z. Thirty-seven options and every single one of them serves 👑

When you name a buffer for a cut, change or yank, the text you're dealing with replaces whatever was chillin' in that buffer before — no mercy. But if you name it with a capital letter, plot twist: the newly cut text gets appended to the buffer instead of overwriting it 🫶. And when you're on that "_ buffer? Literally nothing happens. Which is lowkey iconic for deleting text without touching any of your buffers ✨.

No buffer specified on a cut or change command? Then "1 is the default, and the contents of "1 through "8 each get shifted along one buffer — so the contents of "9 is gone 😭. For a yank command with no buffer specified, it's "0. And finally, a paste command with no specified buffer will paste the text from the most recent command, regardless of any buffer that might have been used with that command. iykyk.

When you call it from a widget function using the zle command, you can optionally pass the buffer as an argument. Like so:

zle vi-set-buffer A

🎀 `vi-set-mark` — `(unbound)` `(m)` `(unbound)`

Set the specified mark right at the cursor position. Drop a pin, basically 📍.

🎀 `set-mark-command` — `(^@)` `(unbound)` `(unbound)`

Set the mark at the cursor position. But if you call it with a negative numeric argument, it does not set the mark — instead it deactivates the region so it's no longer highlighted (tho it's still usable for other purposes, bestie). Otherwise, the region is marked as active 👑.

🎀 `spell-word` — `(ESC-$ ESC-S ESC-s)` `(unbound)` `(unbound)`

Attempt spelling correction on the current word. Your personal autocorrect era 💅.

🎀 `split-undo`

Breaks the undo sequence at the current change. Super useful in vi mode, because changes made in insert mode are coalesced on entering command mode. Same vibe: undo will normally revert as one all the changes made by a user-defined widget. So like, if you want them separate — split it 🪄.

🎀 `undefined-key`

This one runs when a key sequence that isn't bound to any command gets typed. By default, it beeps. Yeah. Just a little beep. That's the whole personality 🔔.

🎀 `undo` — `(^_ ^Xu ^X^U)` `(u)` `(unbound)`

Incrementally undo the last text modification. When it's called from a user-defined widget, it takes an optional argument indicating a previous state of the undo history as returned by the UNDO_CHANGE_NO variable — and modifications are undone until that state is reached, subject to any limit imposed by the UNDO_LIMIT_NO variable ⏪.

Heads up: when invoked from vi command mode, the full prior change made in insert mode is reverted — because those changes were merged when command mode was selected. Sneaky.

🎀 `redo` — `(unbound)` `(^R)` `(unbound)`

Incrementally redo undone text modifications. The comeback tour ⏩.

🎀 `vi-undo-change` — `(unbound)` `(unbound)` `(unbound)`

Undo the last text modification. If repeated, it redoes the modification. It flips back and forth, it's giving indecisive 🎭.

🎀 `visual-mode` — `(unbound)` `(v)` `(unbound)`

Toggle vim-style visual selection mode. If line-wise visual mode is currently enabled, then it's changed to being character-wise. And if you use it following an operator, it forces the subsequent movement command to be treated as a character-wise movement 💜.

🎀 `visual-line-mode` — `(unbound)` `(V)` `(unbound)`

Toggle vim-style line-wise visual selection mode. If character-wise visual mode is currently enabled, then it's changed to being line-wise. And if used following an operator, it forces the subsequent movement command to be treated as a line-wise movement 🔥.

🎀 `what-cursor-position` — `(^X=)` `(ga)` `(unbound)`

Print the character under the cursor, its code as an octal, decimal and hexadecimal number, the current cursor position within the buffer, and the column of the cursor in the current line. Full intel, no cap 🔍.

🎀 `where-is`

Read the name of an editor command and print the listing of key sequences that invoke that specified command. There's a restricted set of editing functions available in the mini-buffer. Keys are looked up in the special command keymap, and if they're not found there, in the main keymap ✨.

🎀 `which-command` — `(ESC-?)` `(unbound)` `(unbound)`

Push the buffer onto the buffer stack, and execute the command which-command cmd, where cmd is the current command. Fun fact: which-command is normally aliased to whence 🕵️‍♀️.

🎀 `vi-digit-or-beginning-of-line` — `(unbound)` `(0)` `(unbound)`

If the last command executed was a digit as part of an argument, it continues the argument. Otherwise, it executes vi-beginning-of-line. Two moods, one binding 🌈.

🌸 Text Objects 🌸

Text objects are commands that can be used to select a block of text according to some criteria. They're a feature of the vim text editor, so they're primarily intended for use with vi operators or from visual selection mode. However — plot twist — they can also be used from vi-insert or emacs mode 🦋.

Key bindings listed below apply to the viopp and visual keymaps. Slay.

💅 `select-a-blank-word` — `(aW)`

Select a word including adjacent blanks, where a word is defined as a series of non-blank characters. With a numeric argument, multiple words will be selected 💖.

💅 `select-a-shell-word` — `(aa)`

Select the current command argument, applying the normal rules for quoting 🎀.

💅 `select-a-word` — `(aw)`

Select a word including adjacent blanks, using the normal vi-style word definition. With a numeric argument, multiple words will be selected ⭐.

💅 `select-in-blank-word` — `(iW)`

Select a word, where a word is defined as a series of non-blank characters. With a numeric argument, multiple words will be selected 🍓.

💅 `select-in-shell-word` — `(ia)`

Select the current command argument, applying the normal rules for quoting. And if the argument begins and ends with matching quote characters, those are not included in the selection — tidy 💅.

💅 `select-in-word` — `(iw)`

Select a word, using the normal vi-style word definition. With a numeric argument, multiple words will be selected 🧚.

✨ CHARACTER HIGHLIGHTING ✨

okay so your line editor can literally highlight characters or whole regions of the line that have some kind of particular significance — and it's all controlled by the array parameter zle_highlight, but only if you set it, bestie. it's opt-in.

if the parameter has the single entry none, every bit of highlighting gets turned off. and like — note that the parameter is still expected to be an array, okay? don't come at it with a scalar. 🙈

otherwise, every entry of the array should be a word that names a context for highlighting, then a colon, then a comma-separated list of the types of highlighting to apply in that context.

the contexts you can use are these 👇

default — any text in the command line that isn't affected by any other highlighting. text outside the editable area of the command line is not affected. periodt.
isearch — when one of the incremental history search widgets is active, this is the area of the command line matched by the search string or pattern.
region — the currently selected text. in emacs terminology this is called the region and it's bounded by the cursor (point) and the mark. it only gets highlighted if it's active, which is the case after the mark is modified with set-mark-command or exchange-point-and-mark. note that whether the region is active or not has no effect on how it's used inside emacs style widgets — it purely determines whether it's highlighted. in vi mode, the region corresponds to selected text in visual mode. slay. 💅
special — individual characters that have no direct printable representation but get shown in a special manner by the line editor. these are described below, keep scrolling 🫶
suffix — this context is used in completion for characters marked as suffixes that will be removed if the completion ends at that point. the most obvious example is a slash (/) after a directory name. note that suffix removal is configurable — the circumstances under which the suffix gets removed may differ for different completions.
paste — following a command to paste text, this is the characters that were inserted. 🍓

when region_highlight is set, the contexts that describe a region — isearch, region, suffix, and paste — get applied first, then region_highlight is applied, then the remaining zle_highlight contexts get applied. and if a particular character gets hit by multiple specifications? the last specification wins. no cap.

🖥️ terminal sequence fields (the lowkey nerdy part)

zle_highlight may also contain extra fields for controlling how the terminal sequences that change colours get output. each of these is followed by a colon and a string in the same form as for key bindings. for the vast majority of terminals you will not need this, because the defaults (shown in parentheses) are widely used. ✨

fg_start_code (\e[3) — the start of the escape sequence for the foreground colour. it's followed by one to three ASCII digits representing the colour. only used for palette colors, i.e. not 24-bit colors specified via a color triplet.
fg_default_code (9) — the number to use instead of the colour to reset the default foreground colour.
fg_end_code (m) — the end of the escape sequence for the foreground colour.
bg_start_code (\e[4) — the start of the escape sequence for the background colour. see fg_start_code above, it's giving same energy.
bg_default_code (9) — the number to use instead of the colour to reset the default background colour.
bg_end_code (m) — the end of the escape sequence for the background colour.

🌈 the types of highlighting

here's what you can actually apply. heads up though: not all types of highlighting are available on all terminals. check your vibe (and your terminal). 🔥

none — no highlighting is applied to the given context. it's not useful for this to show up alongside other types of highlighting; it's there to override a default.
fg=colour — the foreground colour should be set to colour, which can be a decimal integer, the name of one of the eight most widely-supported colours, or a # followed by an RGB triplet in hexadecimal format.

so like — not all terminals support this, and of the ones that do, not all of them provide a way to test the support. hence you gotta decide based on your terminal type. most terminals support the colours black, red, green, yellow, blue, magenta, cyan and white, and you can set those by name. in addition, default may be used to set the terminal's default foreground colour. abbreviations are allowed — b or bl selects black. some terminals may generate additional colours if the bold attribute is also present.

on recent terminals, and on systems with an up-to-date terminal database, you can test how many colours are supported with the command echotc Co. if that succeeds, it indicates a limit on the number of colours that'll be enforced by the line editor. the number of colours is in any case limited to 256 (i.e. the range 0 to 255).

some modern terminal emulators support 24-bit true colour (16 million colours 😭). in that case you can use the hex triplet format — a # followed by either a three or six digit hexadecimal number describing the red, green and blue components of the colour. hex triplets can also be used with 88 and 256 colour terminals via the zsh/nearcolor module (see zshmodules(1)). 💜

also: colour is also known as color. iykyk.

bg=colour — the background colour should be set to colour. works similarly to the foreground colour, except the background isn't usually affected by the bold attribute.
bold — the characters in the given context are shown in a bold font. not all terminals distinguish bold fonts, unfortunately.
standout — the characters in the given context are shown in the terminal's standout mode. the actual effect is specific to the terminal; on many terminals it's inverse video. and on some of those terminals, where the cursor doesn't blink, it appears with standout mode negated — making it less than clear where the cursor actually is 😭. on such terminals, one of the other effects may be preferable for highlighting the region and the matched search string.
underline — the characters in the given context are shown underlined. some terminals show the foreground in a different colour instead; in this case whitespace will not be highlighted.

👻 the `special` characters, explained

the characters we called special up there are these ones. and note: the formatting described here is used irrespective of whether the characters are highlighted. it always happens. 🎀

ASCII control characters — control characters in the ASCII range are shown as ^ followed by the base character.
Unprintable multibyte characters — this one applies to control characters not in the ASCII range, plus other characters as follows. if the MULTIBYTE option is in effect, multibyte characters that aren't in the ASCII character set and are reported as having zero width get treated as combining characters when the option COMBINING_CHARS is on. if that option is off, or if a character appears somewhere a combining character isn't valid, the character is treated as unprintable.

unprintable multibyte characters are shown as a hexadecimal number between angle brackets. the number is the code point of the character in the wide character set — and this may or may not be Unicode, depending on your operating system. 🦋

Invalid multibyte characters — if the MULTIBYTE option is in effect, any sequence of one or more bytes that doesn't form a valid character in the current character set is treated as a series of bytes, each one shown as a special character. you can tell this case apart from other unprintable characters because the bytes are represented as two hexadecimal digits between angle brackets — as distinct from the four or eight digits used for unprintable characters that are nonetheless valid in the current character set.

not all systems support this: for it to work, the system's representation of wide characters must be code values from the Universal Character Set, as defined by IS0 10646 (also known as Unicode). 🧚

Wrapped double-width characters — when a double-width character lands in the final column of a line, it gets shown on the next line instead. the empty space left behind in the original position is highlighted as a special character. lowkey iconic behaviour.

🍓 the defaults

if zle_highlight isn't set, or no value applies to a particular context, the defaults applied are equivalent to:

zle_highlight=(region:standout special:standout
suffix:bold isearch:underline paste:standout)

i.e. both the region and the special characters are shown in standout mode. that's the whole vibe check. 💖

🫶 one last thing

within widgets, arbitrary regions may be highlighted by setting the special array parameter region_highlight — see above, bestie, i didn't forget. ✨

and that's the whole page!! 🎉 this was zsh version 5.9.2, dated July 12, 2026, and you've been reading ZSHZLE(1). go forth and highlight literally everything, you absolute main character. 👑💅🌸

📦 where this page comes from

arch rolling: zsh 5.9.2-1 · custom
nixpkgs unstable: zsh 5.9.2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

ZSHZLE(1)

🌸 NAME 🌸

✨ DESCRIPTION ✨

🔑 KEYMAPS 🔑

📖 Reading Commands 📖

🏠 Local Keymaps 🏠

🛠️ ZLE BUILTINS 🛠️

🌸 vared

🌈 zle

🦋 ZLE WIDGETS 🦋

💜 USER-DEFINED WIDGETS 💜

BUFFER (scalar)

BUFFERLINES (integer)

CONTEXT (scalar)

CURSOR (integer)

CUTBUFFER (scalar)

HISTNO (integer)

ISEARCHMATCH_ACTIVE (integer), ISEARCHMATCH_START (integer), ISEARCHMATCH_END (integer)

KEYMAP (scalar)

KEYS (scalar)

KEYS_QUEUED_COUNT (integer)

killring (array)

LASTABORTEDSEARCH (scalar)

LASTSEARCH (scalar)

LASTWIDGET (scalar)

LBUFFER (scalar)

MARK (integer)

NUMERIC (integer)

PENDING (integer)

PREBUFFER (scalar)

PREDISPLAY (scalar)

POSTDISPLAY (scalar)

🧚 Special Widgets 🧚

👑 STANDARD WIDGETS 👑

💫 Movement 💫

🕰️ History Control 🌸

🦋 history-incremental-pattern-search-backward / history-incremental-pattern-search-forward

🔎 history-search-backward — emacs ESC-P ESC-p · vi cmd unbound · vi ins unbound

🌸 vi-history-search-backward — emacs unbound · vi cmd / · vi ins unbound

🔎 history-search-forward — emacs ESC-N ESC-n · vi cmd unbound · vi ins unbound

🌸 vi-history-search-forward — emacs unbound · vi cmd ? · vi ins unbound

🧚 infer-next-history — emacs ^X^N · vi cmd unbound · vi ins unbound

🌟 insert-last-word — emacs ESC-_ ESC-. · vi cmd unbound · vi ins unbound

🔁 vi-repeat-search — emacs unbound · vi cmd n · vi ins unbound

🔁 vi-rev-repeat-search — emacs unbound · vi cmd N · vi ins unbound

⬆️ up-line-or-history — emacs ^P ESC-[A · vi cmd k · vi ins ESC-[A

🌸 vi-up-line-or-history — emacs unbound · vi cmd - · vi ins unbound

⬆️ up-line-or-search

⬆️ up-history — emacs unbound · vi cmd ^P · vi ins unbound

🔍 history-beginning-search-forward

🎀 set-local-history