READLINE(3)

💖 READLINE(3) · Library Functions Manual 💖

Okay bestie, welcome to readline(3), the library functions manual page 🧚

🎀 NAME 🎀

readline — get a line from a user with editing ✨

🦋 SYNOPSIS 🦋

#include <stdio.h>
#include <readline/readline.h>
#include <readline/history.h>

char *
readline (const char *prompt);

📜 COPYRIGHT 📜

Readline is Copyright (C) 1989-2025 Free Software Foundation, Inc. 🫶

🌸 DESCRIPTION 🌸

okay so readline reads a line from the terminal and returns it 💅 It uses prompt as a prompt. If prompt is NULL or the empty string, readline does not issue a prompt 🙈 The line it hands back is allocated with malloc(3), so YOU are the one who has to free it when you're done 🧹 The returned line has the final newline removed, so only the text of the line is left ✨ Also, it's possible to type characters while quoting them so they skip any readline editing function they'd normally have, which means this line can contain embedded newlines and other special characters 👀 wild, I know 😭

readline gives you editing powers while the user is typing the line 🔥 By default the editing commands are similar to the ones in emacs, and there's also a vi-style editing interface if that's more your vibe 💜

This manual page only covers the most basic use of readline 🌷 there is SO much more functionality, so check out The GNU Readline Library and The GNU History Library for the deets 📚

🍓 RETURN VALUE 🍓

readline returns the text of the line it read ✨ A blank line gives back the empty string 🫧 If EOF shows up while reading a line and that line is empty, readline returns NULL 💀 If EOF is read with a non-empty line, it gets treated as a newline, so no drama 💖

🌈 NOTATION 🌈

This section uses Emacs-style editing concepts and that notation for keystrokes, so pay attention, it's giving nerdy but it's cute 🤓 Control keys are written as C-key, so C-n means Control-N 💅 Meta keys are written as M-key, so M-x means Meta-X 🦋 The Meta key is often labeled “Alt” or “Option” 🫶

On keyboards without a Meta key, M-x means ESC x, which is press and release Escape, then press and release x, in that order 🌸 That makes ESC the meta prefix ✨ The combination M-C-x means ESC Control-x: press and release Escape, then press and hold Control while pressing x, then release both 🔥

On some keyboards the Meta key produces characters with the eighth bit (0200) set 🙈 You can use the enable-meta-key variable to control whether it does that, if the keyboard allows it 💜 On lots of other setups, the terminal or terminal emulator turns the metafied key into a key sequence that starts with ESC, like we just talked about 🧚

If your Meta key produces a key sequence with the ESC meta prefix, you can make M-key key bindings you specify (see Readline Key Bindings below) do the same thing by setting the force-meta-prefix variable 🎀

Readline commands can take numeric arguments, which usually act as a repeat count 🔢 Sometimes though, it's the sign of the argument that matters 👀 Passing a negative argument to a command that works in the forward direction (for example, kill-line) makes that command work backward instead ⏪ Commands whose behaviour with arguments is different from this are noted below 📝

The point is the current cursor position, and mark refers to a saved cursor position 📍 The text between the point and the mark is called the region 🌷

When a command is described as killing text, the deleted text gets saved for possible future retrieval, which is called yanking 🪄 The killed text goes into a kill ring 💍 Consecutive kills pile their deleted text into one unit, so it can be yanked all at once 🫶 Commands that don't kill text separate the chunks of text on the kill ring 🌈

🗂️ INITIALIZATION FILE 🗂️

Readline is customized by putting commands in an initialization file, aka the inputrc file 💅 The name of this file comes from the value of the INPUTRC environment variable ✨ If that variable is unset, the default is ~/.inputrc 🏠 If that file does not exist or can't be read, readline looks for /etc/inputrc 👀 When a program that uses the readline library starts up, readline reads the initialization file and sets the key bindings and variables found there, before reading any user input 🚀

There are only a few basic constructs allowed in the inputrc file 🌸 Blank lines are ignored 🫧 Lines starting with a # are comments 💬 Lines starting with a $ indicate conditional constructs 🔀 Every other line denotes key bindings and variable settings 🎀

The default key bindings in this document can be changed using key binding commands in the inputrc file 💖 Programs that use this library can also add their own commands and bindings 🧚

For example, placing

M-Control-u: universal-argument

or

C-Meta-u: universal-argument

into the inputrc would make M-C-u execute the readline command universal-argument 🔥

Key bindings may contain the following symbolic character names: DEL, ESC, ESCAPE, LFD, NEWLINE, RET, RETURN, RUBOUT (a destructive backspace), SPACE, SPC, and TAB ⌨️

Okay and here's a bonus: in addition to command names, readline lets you bind a key to a string that gets inserted when the key is pressed. That's called a macro 🪄 The difference between a macro and a command is that a macro is enclosed in single or double quotes 💅

🌷 Key Bindings 🌷

The syntax for controlling key bindings in the inputrc file is simple, no cap 🫶 All you need is the name of the command or the text of a macro, plus a key sequence to bind it to 🎀 The key sequence can be specified in one of two ways: as a symbolic key name, possibly with Meta- or Control- prefixes, or as a key sequence made of one or more characters enclosed in double quotes 💜 The key sequence and the name are separated by a colon, and there can be no whitespace between the name and the colon 🙈

When you use the form keyname:function-name or macro, keyname is the name of a key spelled out in English 🇬🇧 For example:

Control-u: universal-argument
Meta-Rubout: backward-kill-word
Control-o: "> output"

In the example above, C-u is bound to the function universal-argument, M-DEL is bound to the function backward-kill-word, and C-o runs the macro on the right hand side (aka it inserts the text “> output” into the line) 🔥

In the second form, "keyseq":function-name or macro, keyseq is different from keyname above, because strings that spell out an entire key sequence can be written by putting the sequence inside double quotes ✨ Some GNU Emacs style key escapes can be used, as in the example below, but none of the symbolic character names are recognized here, so no RETURN in this form 🙅‍♀️

"\C-u": universal-argument
"\C-x\C-r": re-read-init-file
"\e[11~": "Function Key 1"

In this example, C-u is again bound to the function universal-argument 🌸 C-x C-r is bound to the function re-read-init-file, and ESC [ 1 1 ~ is bound to insert the text “Function Key 1” 💖

The full set of GNU Emacs style escape sequences you can use when specifying key sequences is:

• \C- — A control prefix.
• \M- — Adds the meta prefix, or converts the following character to a meta character, as described below under force-meta-prefix.
• \e — An escape character.
• \\ — Backslash.
• \" — Literal ", a double quote.
• \' — Literal ', a single quote.

On top of the GNU Emacs style escapes, there's a second set of backslash escapes too 🎀

• \a — alert (bell) 🔔
• \b — backspace
• \d — delete
• \f — form feed
• \n — newline
• \r — carriage return
• \t — horizontal tab
• \v — vertical tab
• \nnn — The eight-bit character whose value is the octal value nnn (one to three digits) 🔢
• \xHH — The eight-bit character whose value is the hexadecimal value HH (one or two hex digits) 🦋

When you're typing the text of a macro, you have to use single or double quotes to mark it as a macro definition ⚠️ Unquoted text is assumed to be a function name. The backslash escapes listed above get expanded in the macro body. A backslash quotes any other character in the macro text, including " and ', so be careful with those 🙈

Bash lets you display or change the current readline key bindings with the bind builtin command 💻 The -o emacs or -o vi options to the set builtin change the editing mode during interactive use 🔀 Other programs that use this library provide similar mechanisms 🧚 And if a program doesn't offer any other way to add new bindings, a user can always edit the inputrc file and have readline re-read it 📖

🌈 Variables 🌈

Readline has variables you can use to customize its behaviour even further 💅 A variable can be set in the inputrc file with a statement of the form

set variable-name value

Except where noted, readline variables can take the values On or Off (without regard to case) ✨ Unrecognized variable names are ignored 🫧 When readline reads a variable value, empty or null values, “on” (case-insensitive), and “1” are all treated as On 💖 Every other value is treated as Off 🌙

The variables and their default values are:

• active-region-start-color 🌈 (default: the terminfo standout string) — okay so this is a string variable that controls the text color and background for anything in the active region (check enable-active-region below for the deets). It can't take up any physical character positions on the display, so it should only be terminal escape sequences 💅. Readline sends it to the terminal right before it shows the active region text. It gets reset to the default whenever the terminal type changes. The default is the string that puts your terminal in standout mode, pulled from the terminal's terminfo description ✨. A sample value might be “\e[01;33m” 🍓
• active-region-end-color 🦋 (default: the terminfo string that restores standout) — this one is the undo button 🙈. It cancels out active-region-start-color and gets your terminal back to "normal" look after the active region text is shown. Same rules apply: no physical character positions, only escape sequences, and it gets reset whenever the terminal type changes. Readline outputs it after displaying the active region text. The default is the string that restores the terminal from standout mode, again from terminfo 🌸. A sample value might be “\e[0m” 💖
• bell-style 🔔 (default: audible) — this controls what happens when readline wants to ring the terminal bell. Set it to none and readline never rings the bell 🤫. Set it to visible and readline uses a visible bell if one is available ✨. Set it to audible and readline tries to ring the terminal's actual bell 🔥.
• bind-tty-special-chars 🎀 (default: On) — when this is On, readline tries to bind the control characters the kernel's terminal driver treats specially over to their readline equivalents 🧚. These override the default readline bindings described here. Wanna see your current terminal settings, including those special control characters (usually cchars)? Type stty -a at a bash prompt 👀.
• blink-matching-paren 🧚 (default: Off) — if this is On, readline briefly moves the cursor to an opening parenthesis whenever you insert a closing one 💜.
• colored-completion-prefix 🌈 (default: Off) — set it to On and, when readline lists completions, the common prefix of the possible completions shows up in a different color ✨. The color definitions come from the LS_COLORS environment variable. If $LS_COLORS has a color defined for the custom suffix “readline-colored-completion-prefix”, readline uses that color for the common prefix instead of its default 🫶.
• colored-stats 🎨 (default: Off) — with On, readline shows possible completions in different colors so you can tell their file types apart 👑. Those color definitions also come from the LS_COLORS environment variable 🌸.
• comment-begin 💬 (default: “#”) — this is the string the readline insert-comment command inserts 🙈. That command is bound to M-# in emacs mode and to # in vi command mode 🦋.
• completion-display-width 📏 (default: -1) — this is how many screen columns get used to show possible matches when you're doing completion 💅. The value gets ignored if it's less than 0 or greater than the terminal screen width 🙃. Setting it to 0 makes matches display one per line 🍓. The default is -1 ⭐.
• completion-ignore-case 🔤 (default: Off) — On means readline does filename matching and completion in a case-insensitive way 💖.
• completion-map-case 🔀 (default: Off) — if this is On and completion-ignore-case is enabled, readline treats hyphens (-) and underscores (_) as the same thing during case-insensitive filename matching and completion 🫶.
• completion-prefix-display-length ✂️ (default: 0) — this is the max length in characters of the common prefix of your possible completions that gets shown as-is 💜. When it's set above zero, readline swaps out any common prefix longer than this for an ellipsis when showing possible completions ✨. If a completion starts with a period and readline is completing filenames, it uses three underscores instead of an ellipsis 🧚.
• completion-query-items 🙋 (default: 100) — this decides when readline asks if you want to see the possible completions generated by the possible-completions command 👀. It can be set to any integer that's zero or higher 💅. If the number of possible completions is greater than or equal to this value, readline asks whether or not you want to view them. Otherwise it just lists them on the terminal 🌈. A zero value means readline should never ask, and negative values get treated as zero 🫠.
• convert-meta 🔁 (default: On) — with On, readline converts characters it reads that have the eighth bit set into an ASCII key sequence. It does this by clearing the eighth bit and adding an escape character in front, which turns the character into a meta-prefixed one 🦋. The default is On, but readline flips it to Off if the locale has characters whose encodings might include bytes with the eighth bit set 😭. This variable depends on the LC_CTYPE locale category, so it can change if the locale changes 🌍. It also affects key bindings, so check the description of force-meta-prefix below too 🎀.
• disable-completion 🚫 (default: Off) — On means readline stops word completion dead in its tracks 🛑. Completion characters just get inserted into the line as if they'd been mapped to self-insert 💅.
• echo-control-characters 👀 (default: On) — when this is On and your operating system says it supports it, readline echoes a character for any signal generated from the keyboard ⚡.
• editing-mode ⌨️ (default: emacs) — this controls whether readline uses a set of key bindings similar to Emacs or to vi 💜. It can be set to either emacs or vi 🌸.
• emacs-mode-string 🪄 (default: @) — if show-mode-in-prompt is enabled, this string gets shown right before the last line of the primary prompt when emacs editing mode is active 💖. The value is expanded like a key binding, so the usual meta- and control- prefixes and backslash escape sequences all work ✨. The \1 and \2 escapes start and end sequences of non-printing characters, which is handy for sneaking a terminal control sequence into the mode string 🧚.
• enable-active-region 🌟 (default: On) — when this is On, readline lets certain commands mark the region as active 🔦. While the region is active, readline highlights the text in it using the active-region-start-color value, which defaults to the string that turns on the terminal's standout mode 🔥. The active region shows text inserted by bracketed-paste and any matching text found by incremental and non-incremental history searches 🫶.
• enable-bracketed-paste 📋 (default: On) — with On, readline sets up the terminal so each paste goes into the editing buffer as one single string of characters, instead of being treated like each character was typed on the keyboard 🎀. This is called bracketed-paste mode, and it stops readline from running any editing commands bound to key sequences that show up in the pasted text 🛡️.
• enable-keypad ⌨️ (default: Off) — with On, readline tries to turn on the application keypad when it gets called 🦋. Some systems need this to get the arrow keys working 🙏.
• enable-meta-key 🔑 (default: On) — with On, readline tries to enable any meta modifier key the terminal claims to support 💅. On lots of terminals, the Meta key is used to send eight-bit characters. This variable checks for the terminal capability that says the terminal can turn on and off a mode that sets the eighth bit of a character (0200) when the Meta key is held down while typing it (a meta character) 🌈.
• expand-tilde 🏠 (default: Off) — if this is On, readline does tilde expansion when it tries word completion 🫶.
• force-meta-prefix 🧲 (default: Off) — with On, readline changes how it handles key sequences containing \M- or Meta- (see Key Bindings above) 💫. It converts a key sequence like \M-C or Meta-C into the two-character sequence ESC C, which adds the meta prefix 🌸. If force-meta-prefix is Off (the default), readline checks the convert-meta variable to decide whether to do this conversion 🤔. If convert-meta is On, readline does the conversion described above. If it's Off, readline turns C into a meta character by setting the eighth bit (0200) instead 💜.
• history-preserve-point 📍 (default: Off) — with On, the history code tries to put the point in the same spot on each history line you pull up with previous-history or next-history ✨.
• history-size 📚 (default: unset) — this sets the max number of history entries saved in the history list 🍓. If it's set to zero, any existing history entries get deleted and no new ones are saved 💀. If it's set to a value less than zero, the number of history entries isn't limited 🌈. By default the number isn't limited either 🫶. Setting history-size to a non-numeric value sets the max number of history entries to 500 🙈.
• horizontal-scroll-mode ↔️ (default: Off) — setting this to On makes readline use a single line for display. Instead of wrapping to a new line when input gets longer than the screen width, it scrolls the input horizontally on that one line 🦋. This gets switched on automatically for terminals that are 1 line high 📏.
• input-meta 🔢 (default: Off) — with On, readline turns on eight-bit input, meaning it doesn't clear the eighth bit of the characters it reads, no matter what the terminal says it can support 💪. The default is Off, but readline switches it to On if the locale has characters whose encodings might include bytes with the eighth bit set 🌍. This variable depends on the LC_CTYPE locale category, and its value can change if the locale changes 🎀. The name meta-flag is a synonym for input-meta 💜.
• isearch-terminators 🔍 (default: “C-[C-j”)

Okay so this is the rest of search-terminators 💖 It's the string of characters that should end an incremental search without also running that character as a command. If you never give it a value, ESC and C-j end an incremental search for you 🌸

• keymap (emacs) — Sets the current readline keymap 🗝️ The valid names are emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-command, and vi-insert. vi is the same as vi-command, and emacs is the same as emacs-standard. The default is emacs, but the value of editing-mode also affects which keymap you get by default 💅
• keyseq-timeout (500) — This is how long readline waits for another character when it's reading an ambiguous key sequence 🫶 Ambiguous means the input so far could already be a complete sequence, or it could keep going into a longer one. If readline gets no input before the timeout, it goes with the shorter complete sequence. The value is in milliseconds, so 1000 means readline waits one second for more input ⏳ If you set it to a value less than or equal to zero, or to something non-numeric, readline just waits until another key is pressed to decide which sequence to complete 🙈
• mark-directories (On) — When this is On, completed directory names get a slash appended 📁✨
• mark-modified-lines (Off) — When this is On, readline shows history lines that have been modified with a preceding asterisk (*) 🌟
• mark-symlinked-directories (Off) — When this is On, completed names that are symbolic links to directories get a slash appended 🦋 This depends on the value of mark-directories, so it's not fully independent, bestie 💜
• match-hidden-files (On) — When this is On, readline matches files whose names begin with a “.” (hidden files) during filename completion 🕵️‍♀️ If you set it to Off, you have to type the leading “.” yourself in the filename you want completed 🌸
• menu-complete-display-prefix (Off) — When this is On, menu completion shows the common prefix of the list of possible completions (which might even be empty) before it starts cycling through the list 🎀
• output-meta (Off) — When this is On, readline displays characters with the eighth bit set directly, instead of as a meta-prefixed escape sequence 🧚 The default is Off, but readline switches it to On if the locale has characters whose encodings might include bytes with the eighth bit set. This one depends on the LC_CTYPE locale category, so its value can change if the locale changes 🌈
• page-completions (On) — When this is On, readline uses an internal pager that's kind of like more(1) to show one screenful of possible completions at a time 📖
• prefer-visible-bell — See bell-style. 🔔
• print-completions-horizontally (Off) — When this is On, completions are sorted alphabetically across the row instead of going down the screen ➡️
• revert-all-at-newline (Off) — When this is On, readline undoes all changes to history lines before it returns when executing accept-line. By default, history lines can be modified and keep their own individual undo lists across calls to readline() 🔄
• search-ignore-case (Off) — When this is On, readline does both incremental and non-incremental history list searches case-insensitively 🔍
• show-all-if-ambiguous (Off) — This changes how the completion functions behave by default 💁‍♀️ When it's On, words with more than one possible completion list the matches right away instead of just ringing the bell 🛎️
• show-all-if-unmodified (Off) — This works like show-all-if-ambiguous, but with a twist 💫 When it's On, words with more than one possible completion and no partial completion at all (the possible completions don't share a common prefix) list the matches right away instead of ringing the bell 🔔
• show-mode-in-prompt (Off) — When this is On, a string gets added to the beginning of the prompt to show the editing mode: emacs, vi command, or vi insertion 👀 The mode strings are user-settable, like emacs-mode-string 🎨
• skip-completed-text (Off) — When this is On, the default completion behavior changes when a single match gets inserted into the line 🧩 It only kicks in when you're completing in the middle of a word. If it's enabled, readline doesn't insert characters from the completion that match the characters after point in the word being completed, so the bit of the word after the cursor doesn't get duplicated 🙅‍♀️
• vi-cmd-mode-string (((cmd))) — If show-mode-in-prompt is enabled, this string shows up right before the last line of the primary prompt when vi editing mode is active and you're in command mode 🖤 The value gets expanded like a key binding, so the usual meta- and control- prefixes and backslash escape sequences all work here. The \1 and \2 escapes start and end sequences of non-printing characters, which is how you can sneak a terminal control sequence into the mode string 🪄
• vi-ins-mode-string (((ins))) — Same vibe as vi-cmd-mode-string, but this one shows up when vi editing mode is active and you're in insertion mode 💖 It's expanded like a key binding too, with the same meta- and control- prefixes and backslash escapes available, and \1 and \2 work the same way for non-printing characters 🌸
• visible-stats (Off) — When this is On, a character showing a file's type (as reported by stat(2)) gets appended to the filename when possible completions are listed 🗂️

---

✨ Conditional Constructs ✨

Okay this part is giving C preprocessor vibes 🧚 Readline has a facility that works like the conditional compilation features of the C preprocessor, so you can make key bindings and variable settings depend on the result of some tests 💅 There are four parser directives available, bestie 🎀

• $if — The $if construct lets you make bindings based on the editing mode, the terminal you're using, or the application using readline 🌈 The text of the test, after any comparison operator, runs all the way to the end of the line. Unless it says otherwise, you don't need any characters to isolate it 💜
  • mode — The mode= form of the $if directive checks whether readline is in emacs or vi mode 🧠 You can use it together with the set keymap command, for example to set bindings in the emacs-standard and emacs-ctlx keymaps only when readline starts out in emacs mode 🎯
  • term — The term= form lets you include terminal-specific key bindings, maybe to bind the key sequences the terminal sends for its function keys ⌨️ The word on the right side of the = gets tested against both the full name of the terminal and the part of the terminal name before the first -. That means xterm matches both xterm and xterm-256color, for instance 🦋
  • version — The version test lets you compare against specific readline versions 🔢 version expands to the current readline version. The comparison operators are =, (and ==), !=, <=, >=, <, and >. The version number on the right side of the operator is a major version number, an optional decimal point, and an optional minor version (e.g., 7.1). If you leave out the minor version, it defaults to 0 🫶 You can separate the operator from the string version and from the version number with whitespace 💫
  • application — The application construct includes application-specific settings 🧚‍♀️ Each program using the readline library sets its application name, and an initialization file can test for a particular value. This could be used to bind key sequences to functions that are useful for one specific program. For instance, this command adds a key sequence that quotes the current or previous word in bash 🐚

$if Bash
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
$endif

• variable — The variable construct gives you simple equality tests for readline variables and values 📏 The permitted comparison operators are =, ==, and !=. You have to separate the variable name from the comparison operator with whitespace, and the operator can be separated from the value on the right hand side with whitespace too. String and boolean variables can both be tested, but boolean variables have to be tested against the values on and off 🌸

• $else — Commands in this branch of the $if directive run if the test fails 🙃
• $endif — This command, like the one in the previous example, ends an $if command 🛑
• $include — This directive takes a single filename as an argument and reads commands and key bindings from that file 📂 For example, this directive would read /etc/inputrc:

$include  /etc/inputrc

🔍 SEARCHING 🔍

okay so readline has commands for digging through your command history for lines containing a string you pick 💅 there are two search modes: incremental and non-incremental, and they're both lowkey iconic 🧚

Incremental searches start before you've finished typing. Every time you type a character of the search string, readline shows the next history entry that matches what you've typed so far 🦋 you only need as many characters as it takes to find the entry you want, which is so efficient it's giving main character 💖 In emacs editing mode, hit C-r to search backward through history, and C-s to search forward ✨ The characters in the value of the isearch-terminators variable are what end an incremental search. If that variable hasn't been given a value, ESC and C-j end it instead 🫶 Want to bail? C-g aborts the search and puts back your original line 😭 Once the search ends, the history entry that contains your search string becomes the current line 🌸

To find more matches, just hit C-r or C-s again, depending on which way you want to go 🔥 That searches backward or forward for the next entry matching what you've typed so far. Any other key sequence bound to a readline command also ends the search and runs that command instead 💀 For example, a newline ends the search and accepts the line, so the command from history just runs 🚀 A movement command also ends the search, makes the last line found the current line, and starts editing it 🎀

Readline remembers your last incremental search string 🧠 So if you type two C-rs in a row with no new characters for a new search string in between, readline reuses that remembered string 💜

Non-incremental searches wait until you've typed the entire search string before they start looking ⭐ That string can be something you type in, or it can already be part of the current line 🍓

✨ EDITING COMMANDS ✨

okay here's the list of command names and the default key sequences they're bound to 🌈 Commands without a key sequence next to them are unbound by default, so they're just sitting there waiting for you 🙈

quick vocab check before we go 💅 point is where your cursor is right now. mark is a cursor position saved by the set-mark command 📍 The text between point and mark is called the region 🦋 readline also has a concept of an active region: when the region is active, readline's redisplay highlights it using the value of the active-region-start-color variable ✨ The enable-active-region variable turns that highlighting on and off 💖 A few commands set the region to active, and those are noted below 🫶

Commands for Moving

• beginning-of-line (C-a) — jumps you to the start of the current line 🌸 On some keyboards this might also be bound to the Home key 🏠
• end-of-line (C-e) — jumps you to the end of the line 🎀 On some keyboards this might also be bound to the End key 🔚
• forward-char (C-f) — moves you forward one character ➡️ On some keyboards this might also be bound to the right arrow key 👉
• backward-char (C-b) — moves you back one character ⬅️
• forward-word (M-f) — moves forward to the end of the next word 🦋 Words are made of alphanumeric characters, so letters and digits, nothing else 🔢
• backward-word (M-b) — moves back to the start of the current or previous word ✨ Same deal here: words are alphanumeric characters (letters and digits) 🔤
• previous-screen-line — tries to move point to the same physical screen column on the previous physical screen line 🌈 Heads up, this won't do anything useful if the current readline line doesn't take up more than one physical line, or if point isn't greater than the length of the prompt plus the screen width 🙃
• next-screen-line — tries to move point to the same physical screen column on the next physical screen line 💅 Same warning: it won't work if the current readline line doesn't wrap onto more than one physical line, or if the current line's length isn't greater than the length of the prompt plus the screen width 🫠
• clear-display (M-C-l) — clears the screen and, if possible, the terminal's scrollback buffer, then redraws the current line so it sits at the very top of the screen 🧹✨
• clear-screen (C-l) — clears the screen, then redraws the current line, leaving it at the top of the screen 🌸 If you give it a numeric argument, it refreshes the current line without clearing the screen 💜
• redraw-current-line — refreshes the current line 🔄

Commands for Manipulating the History

• accept-line (Newline, Return) — accepts the line no matter where your cursor is 🚀 If the line isn't empty, it may get added to the history list for later recall with add_history() 📚 If the line is a modified history line, it gets restored to its original state 🙈
• previous-history (C-p) — fetches the previous command from the history list, moving back through it 🕰️ On some keyboards this might also be bound to the up arrow key ⬆️
• next-history (C-n) — fetches the next command from the history list, moving forward through it ⏩ On some keyboards this might also be bound to the down arrow key ⬇️
• beginning-of-history (M-<) — jumps to the first line in the history 🥇
• end-of-history (M->) — jumps to the end of the input history, which is the line you're currently typing 🏁
• operate-and-get-next (C-o) — accepts the current line to hand back to the calling application, as if you'd pressed newline 🎀 Then it fetches the line after the current one from history so you can edit it 🦋 If you give it a numeric argument, that number picks which history entry to use instead of the current line 🔢
• fetch-history — with a numeric argument, grabs that entry from the history list and makes it the current line 🧚 With no argument, it moves back to the first entry in the history list 🥇
• reverse-search-history (C-r) — searches backward starting at the current line and moves "up" through history as needed 🔍 This is an incremental search 🦋 This command also sets the region to the matched text and activates the region ✨
• forward-search-history (C-s) — searches forward starting at the current line and moves "down" through history as needed 🔎 This is an incremental search 🌸 This command also sets the region to the matched text and activates the region 💖
• non-incremental-reverse-search-history (M-p) — searches backward from the current line using a non-incremental search for a string you supply 🕵️ The string can match anywhere in a history line 💅
• non-incremental-forward-search-history (M-n) — searches forward through history using a non-incremental search for a string you supply 🕵️‍♀️ The string can match anywhere in a history line 🫶
• history-search-backward — searches backward through history for the characters between the start of the current line and point 🔙 The match has to start at the beginning of a history line 🎯 This is a non-incremental search 🧊 On some keyboards this might be bound to the Page Up key 📄
• history-search-forward — searches forward through history for the characters between the start of the current line and point ⏭️ The match has to start at the beginning of a history line 🎯 This is a non-incremental search 🧊 On some keyboards this might be bound to the Page Down key 📃
• history-substring-search-backward — searches backward through history for the characters between the start of the current line and point 🔙 This time the string can match anywhere in a history line 🌈 This is a non-incremental search 🧊
• history-substring-search-forward — searches forward through history for the characters between the start of the current line and point ⏭️ The string can match anywhere in a history line 🌈 This is a non-incremental search 🧊
• yank-nth-arg (M-C-y) — inserts the first argument to the previous command (usually the second word on the previous line) at point 🎀 With an argument n, it inserts the nth word from the previous command, and the words there start counting at word 0 🔢 A negative argument inserts the nth word counting from the end of the previous command 🔙 Once n is worked out, it uses the history expansion facilities to pull out that word, as if you'd typed the !n history expansion 🧠
• yank-last-arg (M-., M-_) — inserts the last argument to the previous command, which is the last word of the previous history entry 🫶 With a numeric argument, it acts exactly like yank-nth-arg 🔢 Successive calls move back through the history list, inserting the last word (or whichever word the first call's argument picked) from each line in turn 🔁 Any numeric argument given to those repeat calls decides which direction you move through history 🧭 A negative argument flips the direction (back or forward) 🙃 This uses the history expansion facilities to grab the last word, as if you'd typed the !$ history expansion 💅

💅 Commands for Changing Text 💅

• end-of-file (usually C-d) — okay so this is the character your terminal uses to mean "end of file," the one stty(1) sets up for you. If you press it when the line is empty and point is at the very beginning, readline treats it as the end of input and returns EOF. Iconic behavior, honestly. 🫶
• delete-char (C-d) — deletes the character at point. If this is bound to the same key as the tty EOF character (which C-d usually is), check the end-of-file entry above for what happens. On some keyboards it can also be bound to the Delete key. 🗑️
• backward-delete-char (Rubout) — deletes the character behind the cursor. Give it a numeric argument and the deleted text gets saved on the kill ring instead of just vanishing. 💖
• forward-backward-delete-char — deletes the character under the cursor, unless the cursor is at the end of the line. Then it deletes the character behind the cursor instead. Very flexible, no cap. ✨
• quoted-insert (C-q, C-v) — adds the next character you type to the line verbatim. This is how you insert characters like C-q itself, for example. 🙈
• tab-insert (M-TAB) — inserts a tab character. Simple, but make it a moment. 🌸
• self-insert (a, b, A, 1, !, ...) — inserts whatever character you typed. The everyday main character of this whole page. 🎀
• bracketed-paste-begin — this one is meant for the "bracketed paste" escape sequence some terminals send, and it's bound by default, so you don't have to do anything. It lets readline insert your pasted text as one single unit instead of treating every character like a separate keypress. The pasted characters go in as if each one was bound to self-insert, so no editing commands get run mid-paste. Protective energy. 🛡️🦋 Bracketed paste sets the region to the inserted text and activates the region. ✨
• transpose-chars (C-t) — drags the character before point forward over the character at point, and point moves forward too. If point is at the end of the line, it transposes the two characters before point instead. Negative arguments have no effect here, so don't bother. 🔄
• transpose-words (M-t) — drags the word before point past the word after point, and point moves past that word as well. If point is at the end of the line, it transposes the last two words on the line. Words swapping places, it's giving drama. 👑
• upcase-word (M-u) — uppercases the current (or following) word. With a negative argument, it uppercases the previous word instead, and point stays exactly where it is. 🔥
• downcase-word (M-l) — lowercases the current (or following) word. With a negative argument, it lowercases the previous word, but point doesn't move. Quiet but powerful. 🌙
• capitalize-word (M-c) — capitalizes the current (or following) word. With a negative argument, it capitalizes the previous word, and point stays put. Respectfully, very cute. 🎀
• overwrite-mode — toggles overwrite mode. With an explicit positive numeric argument, it switches to overwrite mode. With an explicit non-positive numeric argument, it switches to insert mode. This only affects emacs mode, because vi mode does overwrite its own way. 💅 Every call to readline() starts in insert mode, so you always begin fresh. 🌈 In overwrite mode, characters bound to self-insert replace the text at point instead of pushing everything to the right. Characters bound to backward-delete-char replace the character before point with a space. By default this command is unbound, but on some keyboards it can be bound to the Insert key. 🦋

🌊 Killing and Yanking 🌊

• kill-line (C-k) — kills the text from point to the end of the current line. With a negative numeric argument, it kills backward from the cursor to the beginning of the line instead. 💀
• backward-kill-line (C-x Rubout) — kills backward to the beginning of the current line. With a negative numeric argument, it kills forward from the cursor to the end of the line. Opposite-day vibes. 🙃
• unix-line-discard (C-u) — kills backward from point to the beginning of the line, saving the killed text on the kill-ring. 🧹
• kill-whole-line — kills all characters on the current line, no matter where point is. Full clear, no mercy. 💥
• kill-word (M-d) — kills from point to the end of the current word. If you're sitting between words, it kills up to the end of the next word. Word boundaries here are the same ones forward-word uses. 🍓
• backward-kill-word (M-Rubout) — kills the word behind point. Word boundaries are the same as the ones backward-word uses. 🫧
• unix-word-rubout (C-w) — kills the word behind point, using white space as the word boundary, and saves the killed text on the kill-ring. Classic. 🎀
• unix-filename-rubout — kills the word behind point, using white space and the slash character as word boundaries, and saves the killed text on the kill-ring. Perfect for paths, bestie. 📁
• delete-horizontal-space (M-\) — deletes all spaces and tabs around point. Tidy girl behavior. ✨
• kill-region — kills the text in the current region. 🔪
• copy-region-as-kill — copies the text in the region to the kill buffer, so you can yank it right away without losing the original. 🌸
• copy-backward-word — copies the word before point to the kill buffer. Word boundaries are the same as backward-word. 📋
• copy-forward-word — copies the word following point to the kill buffer. Word boundaries are the same as forward-word. 📋
• yank (C-y) — yanks the top of the kill ring into the buffer at point. Bringing the good stuff back. 🧚
• yank-pop (M-y) — rotates the kill ring and yanks the new top. This only works if the previous command was yank or yank-pop, so keep that in mind. 🔁

🔢 Numeric Arguments 🔢

• digit-argument (M-0, M-1, ..., M--) — adds this digit to the argument already accumulating, or starts a new argument if there isn't one. M-- starts a negative argument. 🔢
• universal-argument — another way to set an argument, no cap. If you follow this command with one or more digits (optionally with a leading minus sign), those digits become the argument. If you follow it with digits and then run universal-argument again, that ends the numeric argument, but the second call is otherwise ignored. 🫶 As a special case, if universal-argument is immediately followed by a character that is neither a digit nor a minus sign, the argument count for the next command gets multiplied by four. The count starts at one, so the first run makes it four, a second run makes it sixteen, and so on, each time multiplying by four. Exponential slay. 📈

🗨️ Completing 🗨️

• complete (TAB) — attempts completion on the text before point. The actual completion is application-specific, so it depends on who's running it. 🤷‍♀️ Bash, for instance, tries programmable completion first. If that doesn't work, it treats the text as a variable (if it begins with $), a username (if it begins with ~), a hostname (if it begins with @), or a command (including aliases, functions, and builtins), checking each in turn. If none of those produce a match, it falls back to filename completion. 🐚 Gdb, on the other hand, lets you complete program functions and variables, and only attempts filename completion under certain circumstances. 🐛 The default readline completion is filename completion. 📂
• possible-completions (M-?) — lists the possible completions of the text before point. When it displays them, readline sets the number of columns used for display to the first of these that applies, in this order: the value of completion-display-width, the value of the environment variable COLUMNS, or the screen width. 📜
• insert-completions (M-*) — inserts all completions of the text before point that possible-completions would have generated, separated by a space. 🧁
• menu-complete — similar to complete, except it replaces the word being completed with a single match from the list of possible completions. Run it again and it steps through the list, inserting each match in turn. When it gets to the end of the list, menu-complete rings the bell (depending on the bell-style setting) and restores the original text. An argument of n moves n positions forward through the matches, and a negative argument moves backward. This is meant to be bound to TAB, but it's unbound by default. 🎠
• menu-complete-backward — identical to menu-complete, except it moves backward through the list, as if menu-complete had been given a negative argument. Also unbound by default. ⏪
• export-completions — performs completion on the word before point the way described above, then writes the list of possible completions to readline's output stream. It uses this format, with each piece on its own line:
  • the number of matches N;
  • the word being completed;
  • S:E, where S and E are the start and end offsets of the word in the readline line buffer; then
  • each match, one per line

If there are no matches, the first line is 0, and this command doesn't print anything after the S:E. If there's only a single match, it prints a single line containing that match. If there's more than one match, it prints the common prefix of the matches on the first line after the S:E (this prefix may be empty), then the matches on the lines after that. In this case, N includes the line with the common prefix. 📤

The user or application needs to be ready for a blank line, because it can totally happen. The intent is that the user or application reads N lines after the line containing S:E to get the match list. This command is unbound by default. 🙈

• delete-char-or-list — deletes the character under the cursor if you're not at the beginning or end of the line (just like delete-char). At the end of the line, it acts exactly like possible-completions. Unbound by default. 🧠

🎬 Keyboard Macros 🎬

• start-kbd-macro (C-x () — begins saving the characters you type into the current keyboard macro. Recording mode, activate. 🔴
• end-kbd-macro (C-x )) — stops saving the characters into the current keyboard macro and stores the definition. Cut! 🎬
• call-last-kbd-macro (C-x e) — re-executes the last keyboard macro you defined, making its characters appear as if you typed them at the keyboard all over again. Replay. 🔁✨
• print-last-kbd-macro () — prints the last keyboard macro you defined, in a format that works for the inputrc file. Copy-paste it and you're set. 🖨️💜

✨ Miscellaneous ✨

re-read-init-file (C-x C-r) 📜

okay so this one just re-reads your inputrc file 🎀 and brings in any bindings or variable assignments it finds in there. no restart needed, bestie 💖

abort (C-g) 🙅‍♀️

this is your "nope, cancel that" button 💀 it aborts the current editing command and rings the terminal's bell, but only if that matches your bell-style setting. so it's giving polite little ding or total silence depending on how you set it up 🔔

do-lowercase-version (M-A, M-B, M-x, ...) 🔠

if the metafied character x is uppercase, this runs whatever command is bound to the lowercase version of that same metafied character ✨ the behavior is undefined if x is already lowercase, so ngl just don't go there 😭

prefix-meta (ESC) 🦋

this one metafies the next character you type. so ESC f is the same thing as Meta-f. iconic shortcut energy 💅

undo (C-_, C-x C-u) ⏪

incremental undo 🌸 and it's remembered separately for each line, so your undos stay in their own little lane 🫶

revert-line (M-r) 🫣

this undoes all changes made to the line, like the nuclear option 💥 it's basically the same as running the undo command enough times to get the line back to how it started. full reset, no cap 🧹

tilde-expand (M-~) 🏠

performs tilde expansion on the current word 🍓 simple, clean, slay.

set-mark (C-@, M-<space>) 📍

sets the mark to the point where your cursor currently is 📌 but if you give it a numeric argument, it puts the mark at that position instead. marking your spot, periodt ✨

exchange-point-and-mark (C-x C-x) 🔄

swaps the point with the mark 💜 so your cursor jumps to the saved position, and then the mark gets set to where your cursor used to be. it's a little switcheroo and honestly so satisfying 😭

character-search (C-]) 🔍

reads a character and moves point to the next occurrence of that character 🧚 a negative argument makes it search for previous occurrences instead, so you can go backwards too 🔙

character-search-backward (M-C-]) ⬅️

reads a character and moves point to the previous occurrence of that character 🌈 a negative argument flips it and searches for subsequent occurrences. backwards is forwards if you're brave enough 🙈

skip-csi-sequence 🫧

okay this one is lowkey important 🥺 it reads enough characters to eat up a multi-key sequence, like the ones for keys such as Home and End. CSI sequences start with a Control Sequence Indicator (CSI), which is usually ESC [. if this sequence is bound to "\e[", then keys that produce CSI sequences do nothing unless you've explicitly bound them to a readline command. so no stray characters sneaking into your editing buffer 🙅‍♀️✨ this one is unbound by default, but it's usually bound to ESC [.

insert-comment (M-#) 💬

without a numeric argument, this inserts the value of the readline comment-begin variable at the beginning of the current line 🎀 with a numeric argument it becomes a toggle 🔀: if the characters at the start of the line don't match the value of comment-begin, it inserts the value. otherwise, it deletes the characters in comment-begin from the start of the line. either way, the line gets accepted like you hit newline. the default value of comment-begin makes the current line a shell comment 🐚, and if a numeric argument removes that comment character, the line will get executed by the shell. ⚠️ heads up, that's a spicy move, so double-check before you do it 😭

dump-functions 🖨️

prints all of the functions and their key bindings to the readline output stream 📋 if you give it a numeric argument, the output gets formatted so you can paste it straight into an inputrc file 💖

dump-variables 🗂️

prints all of the settable variables and their values to the readline output stream 🌷 same deal with a numeric argument: the output is formatted so it can become part of an inputrc file ✨

dump-macros 🧾

prints all of the readline key sequences bound to macros, plus the strings they output, to the readline output stream 🍬 and with a numeric argument, it's formatted to be part of an inputrc file, obsessed 😍

execute-named-command (M-x) 🎯

reads a bindable readline command name from your input and runs the function it's bound to, as if the key sequence it's bound to showed up in the input 🪄 if you give this one a numeric argument, it passes that argument along to the function it executes.

emacs-editing-mode (C-e) 🔁

when you're in vi command mode, this switches readline over to emacs editing mode 💜

vi-editing-mode (M-C-j) 🌙

when you're in emacs editing mode, this switches you over to vi editing mode 🦋 pick your vibe, bestie 🫶

🎀 DEFAULT KEY BINDINGS 🎀

okay so here's the default keymap list, bestie 💅 Anything with the eighth bit set gets written as M-<character>, and those are called metafied characters 🦋 Every printable ASCII character that isn't on the emacs standard list is bound to self-insert, which just drops that character into your input line ✨ In vi insertion mode, anything not specifically listed is also self-insert 🫶 Characters that stty(1) or the terminal driver already handle for signals, like C-Z or C-C, keep that job 💀 Upper and lower case metafied characters do the same thing in the emacs mode meta keymap 🌸 And whatever's left over is unbound, which makes readline ring the bell 🔔 (that depends on the bell-style variable, so it's not always a bell 🙈)

🌸 Emacs Mode 🌸

✨ Emacs Standard bindings ✨

"C-@"  set-mark
"C-A"  beginning-of-line
"C-B"  backward-char
"C-D"  delete-char
"C-E"  end-of-line
"C-F"  forward-char
"C-G"  abort
"C-H"  backward-delete-char
"C-I"  complete
"C-J"  accept-line
"C-K"  kill-line
"C-L"  clear-screen
"C-M"  accept-line
"C-N"  next-history
"C-P"  previous-history
"C-Q"  quoted-insert
"C-R"  reverse-search-history
"C-S"  forward-search-history
"C-T"  transpose-chars
"C-U"  unix-line-discard
"C-V"  quoted-insert
"C-W"  unix-word-rubout
"C-Y"  yank
"C-]"  character-search
"C-_"  undo
" " to "/"  self-insert
"0"  to "9"  self-insert
":"  to "~"  self-insert
"C-?"  backward-delete-char

💜 Emacs Meta bindings 💜

"M-C-G"  abort
"M-C-H"  backward-kill-word
"M-C-I"  tab-insert
"M-C-J"  vi-editing-mode
"M-C-L"  clear-display
"M-C-M"  vi-editing-mode
"M-C-R"  revert-line
"M-C-Y"  yank-nth-arg
"M-C-["  complete
"M-C-]"  character-search-backward
"M-space"  set-mark
"M-#"  insert-comment
"M-&"  tilde-expand
"M-*"  insert-completions
"M--"  digit-argument
"M-."  yank-last-arg
"M-0"  digit-argument
"M-1"  digit-argument
"M-2"  digit-argument
"M-3"  digit-argument
"M-4"  digit-argument
"M-5"  digit-argument
"M-6"  digit-argument
"M-7"  digit-argument
"M-8"  digit-argument
"M-9"  digit-argument
"M-<"  beginning-of-history
"M-="  possible-completions
"M->"  end-of-history
"M-?"  possible-completions
"M-B"  backward-word
"M-C"  capitalize-word
"M-D"  kill-word
"M-F"  forward-word
"M-L"  downcase-word
"M-N"  non-incremental-forward-search-history
"M-P"  non-incremental-reverse-search-history
"M-R"  revert-line
"M-T"  transpose-words
"M-U"  upcase-word
"M-X"  execute-named-command
"M-Y"  yank-pop
"M-\"  delete-horizontal-space
"M-~"  tilde-expand
"M-C-?"  backward-kill-word
"M-_"  yank-last-arg

🦋 Emacs Control-X bindings 🦋

"C-XC-G"  abort
"C-XC-R"  re-read-init-file
"C-XC-U"  undo
"C-XC-X"  exchange-point-and-mark
"C-X("  start-kbd-macro
"C-X)"  end-kbd-macro
"C-XE"  call-last-kbd-macro
"C-XC-?"  backward-kill-line

🧚 VI Mode bindings 🧚

okay now the vi side, which is giving a whole different personality 🍓 Everything here is grouped by which mode you're in, insert or command 💖

🫧 VI Insert Mode functions 🫧

"C-D"  vi-eof-maybe
"C-H"  backward-delete-char
"C-I"  complete
"C-J"  accept-line
"C-M"  accept-line
"C-N"  menu-complete
"C-P"  menu-complete-backward
"C-R"  reverse-search-history
"C-S"  forward-search-history
"C-T"  transpose-chars
"C-U"  unix-line-discard
"C-V"  quoted-insert
"C-W"  vi-unix-word-rubout
"C-Y"  yank
"C-["  vi-movement-mode
"C-_"  vi-undo
" " to "~"  self-insert
"C-?"  backward-delete-char

👑 VI Command Mode functions 👑

"C-D"  vi-eof-maybe
"C-E"  emacs-editing-mode
"C-G"  abort
"C-H"  backward-char
"C-J"  accept-line
"C-K"  kill-line
"C-L"  clear-screen
"C-M"  accept-line
"C-N"  next-history
"C-P"  previous-history
"C-Q"  quoted-insert
"C-R"  reverse-search-history
"C-S"  forward-search-history
"C-T"  transpose-chars
"C-U"  unix-line-discard
"C-V"  quoted-insert
"C-W"  vi-unix-word-rubout
"C-Y"  yank
"C-_"  vi-undo
" "  forward-char
"#"  insert-comment
"$"  end-of-line
"%"  vi-match
"&"  vi-tilde-expand
"*"  vi-complete
"+"  next-history
","  vi-char-search
"-"  previous-history
"."  vi-redo
"/"  vi-search
"0"  beginning-of-line
"1" to "9"  vi-arg-digit
";"  vi-char-search
"="  vi-complete
"?"  vi-search
"A"  vi-append-eol
"B"  vi-prev-word
"C"  vi-change-to
"D"  vi-delete-to
"E"  vi-end-word
"F"  vi-char-search
"G"  vi-fetch-history
"I"  vi-insert-beg
"N"  vi-search-again
"P"  vi-put
"R"  vi-replace
"S"  vi-subst
"T"  vi-char-search
"U"  revert-line
"W"  vi-next-word
"X"  vi-rubout
"Y"  vi-yank-to
"\"  vi-complete
"^"  vi-first-print
"_"  vi-yank-arg
"`"  vi-goto-mark
"a"  vi-append-mode
"b"  vi-prev-word
"c"  vi-change-to
"d"  vi-delete-to
"e"  vi-end-word
"f"  vi-char-search
"h"  backward-char
"i"  vi-insertion-mode
"j"  next-history
"k"  previous-history
"l"  forward-char
"m"  vi-set-mark
"n"  vi-search-again
"p"  vi-put
"r"  vi-change-char
"s"  vi-subst
"t"  vi-char-search
"u"  vi-undo
"w"  vi-next-word
"x"  vi-delete
"y"  vi-yank-to
"|"  vi-column
"~"  vi-change-case

🌈 SEE ALSO 🌈

• The Gnu Readline Library, Brian Fox and Chet Ramey
• The Gnu History Library, Brian Fox and Chet Ramey
• bash(1)

📁 FILES 📁

• ~/.inputrc — the individual readline initialization file ✨

🦋 AUTHORS 🦋

okay the credits, bestie 🫶

• Brian Fox, Free Software Foundation
• bfox@gnu.org
• Chet Ramey, Case Western Reserve University
• chet.ramey@case.edu

🐛 BUG REPORTS 🐛

if you find a bug in readline, you should totally report it 😭 But first, make sure it's really a bug, and that it shows up in the latest version of the readline library you have 🔍

Once you've confirmed it's a real bug, mail a bug report to bug-readline@gnu.org 💌 If you have a fix, you're welcome to send that too, periodt 🔥 Suggestions and "philosophical" bug reports can go to bug-readline@gnu.org or get posted to the Usenet newsgroup gnu.bash.bug 🌸

Comments and bug reports about this manual page should go to chet.ramey@case.edu 💜

💀 BUGS 💀

it's too big and too slow 🙈

---

and that's the whole page, bestie 💖 Readline 8.3, last updated December 30, 2024, filed under READLINE(3) ✨🎀