rlwrap(1)

📦
version 0.48 · 7 versions
, in alpine 3.24, arch rolling

💖 NAME 💖

rlwrap(1) — rlwrap is the readline wrapper. That's the whole vibe, bestie. ✨

✨ SYNOPSIS ✨

rlwrap [rlwrap-options] command ...

🌸 DESCRIPTION 🌸

Okay so rlwrap runs the specified command, intercepting user input so you get readline's line editing, persistent history, and completion. It's giving "your terminal but upgraded" 💅

rlwrap tries (and almost succeeds) to be completely transparent — you (or your shell) shouldn't notice any difference between command and rlwrap command, except the added readline functionality, of course. This should even hold true when you are re-directing, piping, and sending signals from and to command, and when command manipulates its terminal settings, working directory, or (with the -U option) command line. No cap, it's lowkey invisible like that 🫶

There are many options to add (programmable) completion, handle multi-line input, colour, and re-write prompts. If you don't need them (and you probably don't), you can skip the rest of this manpage, although some of those options could make your command line quite a bit more comfortable... 👑

💅 OPTIONS 💅

  • -a[password_prompt], --always-readline[=password_prompt] — Always remain in "readline mode" (see below), regardless of command's terminal settings. If rlwrap "does nothing", this is the option to use, because command is apparently already doing its own line editing. NB: with this option, rlwrap will echo (and save) passwords, unless you give command's password prompt as an argument.

The argument is optional; if given, it has to directly follow a short option without an intervening space (-aPassword:) and a long option with an equals sign (--always-readline=Password:).

The -N (--no-children) option can be used to avoid wrappiOBng pagers and editors called from command; this should make them much more usable.

  • -A[!], --ansi-colour-aware[=!] — Prompts that use colour, or use other CSI codes to e.g. set window titles or enable bracketed-paste, will confuse rlwrap, especially at the end of long input lines. This option will usually (but by no means always) make rlwrap better behaved in such cases. 🎀

Giving '!' as an argument will make rlwrap remove all color codes from the prompt.

The argument is optional; if given, it has to directly follow a short option without an intervening space (-A!) and a long option with an equals sign (--ansi-colour-aware=!).

  • -b, --break-chars list_of_characters — Consider the specified characters word-breaking. This determines what is considered a "word", both when completing and when building a completion word list from files specified by -f options following (not preceding!) it. Default list: (){}[],'+-=&^%$#@";|\ Unless -c is specified, / and . (period) are added to this default list. Whitespace is always considered word-breaking, except if you prefix the list with "precisely:". For example: -b $'precisely:\t' will break on tabs, but not on spaces, or anything else. Due to a limitation in rlwrap, newlines are always word-breaking.
  • -c, --complete-filenames — Complete filenames (filename completion is always case-sensitive, even with the -i option). On Linux, OS X, FreeBSD and Solaris, rlwrap will keep track of command's working directory, so that relative filenames will be completed as one would expect. 🦋
  • -C, --command-name command_name|N — Use command_name instead of command to determine the names of history and completion files, and to evaluate $if command_name conditionals in $INPUTRC. A numeric argument N > 0 means: use the Nth argument as the command_name (counting backwards from the end of the argument list).
  • -D, --history-no-dupes n — How aggressively to weed out duplicate entries from the input history. If n = 0, all inputs are kept in the history list; if n = 1 (this is the default), consecutive duplicates are dropped from the list; while n = 2 will make rlwrap drop all previous occurrences (in the current session) of the current input from the list.

Using -D 2 in combination with the operate-and-get-next key may shuffle history items around in an unpredictable way! 😭

  • -e, --extra-char-after-completion char — By default, rlwrap appends a space after any inserted completion text. Use this option to change this to '' (don't insert anything) or some other character.
  • -E, --always-echo — By default, rlwrap avoids displaying passwords by echoing '***' whenever the client clears the ECHO flag on its input. This option will make rlwrap ignore this ECHO flag and always echo the user's input. (-aPassword: will still work as expected.)
  • -f, --file file — Split file into words (using the default word-breaking characters, or those specified by a preceding --break-chars option), and add them to the completion word list. This option can be given more than once, and adds to the default completion list in $RLWRAP_HOME or /usr/share/rlwrap/completions.

Specifying -f . will make rlwrap use the current history file as a completion word list.

  • -g, --forget-matching regexp — Forget (i.e. never put into the history list) input lines that match the POSIX 1003.2 regular expression regexp. A common use case would be -g '^[[:blank:]]' (or simply -g '^ ') to not remember input lines that start with a space. The match is always case-insensitive. perl-style character classes like '\d' are not recognised, use '[[:digit:]]'. For more about regular expressions, see regex (7).
  • -h, --help — Print a short help message. Short and sweet, bestie 🫶
  • -H, --history-filename file — Read command history from file (and write it back there if --histsize >= 0).
  • -i, --case-insensitive — Ignore case when completing (filename completion remains case-sensitive). This option has to come before any -f options.
  • -I, --pass-sigint-as-sigterm — Send a TERM signal to command when an INT is received (e.g. when you press CTRL-C).
  • -l, --logfile file — When in readline mode, append command's output (including echo'ed user input) to file (creating file when it doesn't exist).
  • -m[newline_substitute], --multi-line[=newline_substitute] — Enable multi-line input using a "newline substitute" character sequence (" \ ", [space-backslash-space] by default). Newline substitutes are translated to newlines before sending the input to command. With this option, you can call an external editor $RLWRAP_EDITOR on the (expanded) current input with the rlwrap_call_editor key (CTRL-^ by default). The argument is optional; if given, it has to directly follow a short option without an intervening space (-m';;') and a long option with an equals sign (--multi-line=';;').
  • -M, --multi-line-ext .ext — Call multi-line-editor on temporary files with filename extension .ext (useful for e.g. automatic syntax colouring).
  • -n, --no-warnings — Don't print warnings.
  • -N, --no-children — When rlwrap is invoked with the --always-readline option, editors and pagers that are called by the client will be pretty unusable, as they will see your keypresses only if you press ENTER. rlwrap -N will avoid this problem by switching to direct mode if it thinks command is waiting for one of its children.
  • -o, --one-shot — Send an EOF to command after accepting the first line of input.
  • -O, --only-cook regexp — Only ever "cook" prompts that match regexp, which can be preceded by '!', meaning that all matching candidate prompts will be cooked immediately ("confident mode").
  • -p[colour], --prompt-colour[=colour] — Use one of the colour names black, red, green, yellow, blue, cyan, purple (=magenta) or white, or an ANSI colour code like $'\033[1;33m' or 'ESC[38;5;209m'. An uppercase colour name (Yellow or YELLOW) results in a bold prompt. Prompts that already contain (colour) escape sequences or one of the readline "ignore markers" (ASCII 0x01 and 0x02) are never coloured. This option implies --ansi-colour-aware. Google for 'ANSI color' to learn more about colour codes. The argument is optional; if given, it has to directly follow a short option without an intervening space (-p'Red') and a long option with an equals sign (--prompt-colour='Red').
  • -P, --pre-given text — Start rlwrap with text in its edit buffer (this will automatically set the --always-readline option).
  • -q, --quote-characters list_of_characters — Assume that the given characters act as quotes when matching parentheses. Take care to escape the list properly for your shell (example: -q "\"'", which happens to be the default, or -q "\"" which will be better for lisp input).
  • -r, --remember — Put all words seen on in- and output on the completion list.
  • -R, --renice — Make rlwrap nicer than command (cf nice (1)). This may prevent rlwrap from interrupting command to display a prompt when command is still "thinking" about what to output next.
  • -s, --histsize N — Limit the history list to N entries, truncating the history file (default: 300). A negative size -N (even -0) means the same as N, but treats the history file as read-only.
  • -S, --substitute-prompt prompt — Substitute the specified prompt for command's own prompt. Mainly useful when command doesn't have a prompt.
  • -t, --set-terminal-name name — Set command's TERM to name. Programs that confuse rlwrap with fancy screen control codes can sometimes be tamed by specifying -t dumb.
  • -U, --mirror-arguments — (linux only) Keep track of command's arguments as seen by the ps (1) command, and mirror them in rlwrap's own arguments. This can be useful for commands that overwrite command-line password arguments that would be exposed by rlwrap without this option. The mirroring takes place only after the first user input, or already after a few milliseconds, if you use the --polling option (which is what you probably want if you want to hide the command line).
  • -v, --version — Print rlwrap version.
  • -w, --wait-before-prompt timeout — okay so here's the tea: to figure out whether command's last output is a prompt, rlwrap waits timeout milliseconds after receiving it. Only when no more output has arrived does it get cooked (coloured, filtered and/or replaced by a substitute prompt) and displayed as a prompt. Before that, the prompt shows up "uncooked". Most users won't even notice 🙈, but heavy cookers can prepend the timeout with a minus sign, which makes rlwrap hold back the prompt until it's been cooked — that's "patient mode" ✨. It prevents the prompt from flashing, but it'll also interfere with long output lines and make switches from direct to readline mode less reliable. Default timeout: 40 ms ⏱️
  • -W, --polling — wake up every timeout millisecs, where timeout is the same as for the -w (--wait-before-prompt) option, 40 ms by default. Why? To sense the slave's interrupt character and ISIG flag and adjust stdin's terminal settings accordingly, even before you press a key 👀. Try this option e.g. when CTRL+C acts differently on command with, and without, rlwrap. Iconic troubleshooting behavior honestly.
  • -X, --skip_setctty — don't create a new session for command: command will inherit the controlling terminal of the process that invokes rlwrap. Lowkey useful for wrapping commands that spawn children that are expected to stay running (in particular: not receive a SIGHUP) when the command itself exits 🫶
  • -z, --filter filter — use filter to change rlwrap's behaviour. Filters are small python or perl scripts that rlwrap runs in order to re-write or suppress input, output, prompts, history items and even signals 👑. They can keep sensitive input out of the history, implement simple macros, programmable hotkeys for e.g. fuzzy history search, and programmable completion. rlwrap comes with a perl and a python module to make filter writing easy (cf. RlwrapFilter(3pm) for the perl module — the python one is very similar, iykyk). A bunch of example filters are installed in the directory /usr/share/rlwrap/filters.

So like, run this:

rlwrap -z listing

and it lists all currently installed filters, while

rlwrap -z filter

displays information about filter 💅

If filter needs arguments, you should quote the whole filter command line, bestie:

rlwrap -z 'filter args' command ...
rlwrap -z 'pipeline filter1 ... : filter2 ... : ...' command ...

If this command line contains shell metacharacters, rlwrap passes it to the system shell for parsing. No cap.

Now, filters have to follow a special protocol, so shell commands like sed and grep cannot be used as rlwrap filters 🫠. They can, however, be converted into filters by the makefilter filter:

rlwrap -z 'makefilter egrep -i --color "error|$"' command

will color all occurrences of "error" (or "Error") in command's output, while

rlwrap -z 'makefilter --message-type history sed -e s"/whisky/lemonade/"' command

sanitises your drinking history 🍸🍋. Both filters can be combined using the pipeline filter, of course. Slay.

✨ EXAMPLES ✨

Run nc (netcat) with command-line editing and history:

rlwrap nc

Wrap smbclient (which uses readline itself), keep passwords out of the history and don't interfere with pagers (like less) called by smbclient:

rlwrap -aPassword: -N smbclient //PEANUT/C

Wrap sensitive_app, hide password from ps (if sensitive_app does so) and keep all input that starts with a space out of history:

rlwrap -g '^ ' -U sensitive_app --password MySeCrEt

Wrap gauche (a Scheme interpreter) with a bold blue prompt, enable multi-line editing (using .scm as filename extension) and don't consider single quotes as quotes (so that the parentheses in e.g. (print 'q) match):

rlwrap -pBlue -m -M .scm -q'"' gosh

Wrap sqlite3, use the pipeto filter to be able to pipe the output of SQL commands through grep and/or less, complete (case-insensitively) on the SQL keywords in sql_words:

rlwrap -a -z pipeto -i -f sql_words sqlite3 contacts.db

In a shell script, use rlwrap in 'one-shot' mode as a replacement for read:

order=$(rlwrap -pYellow -S 'Your pizza? ' -H past_orders -P Margherita -o cat)

🦋 DIRECT MODE AND READLINE MODE 🦋

Most simple console commands put your terminal either in "cooked" or in "raw" mode. In cooked mode the terminal will wait until you press the ENTER key before handing the entire line to the program; in raw mode every key you press is handed down immediately ⚡. In cooked mode you generally can use the backspace key, but not the arrow keys, to edit your input.

When you rlwrap command, rlwrap will run it in a separate session, under its own (controlling) "pseudo-terminal" (pty), and monitor this pty to see whether it is in raw, or in cooked mode. In the first case, rlwrap will copy all input and output directly between command and your terminal ("direct mode"). In the second case, rlwrap will use readline to edit your input ("readline mode"), and monitor command's output — every last line that doesn't end with a newline is a potential prompt 👀. How it handles such a candidate prompt depends on its being in "patient" or "impatient" mode, see below 💖

Simple console commands use cooked mode whenever they want whole input lines, and raw mode when they want single keypresses. Those are the programs for which rlwrap is most useful 🫶. More sophisticated commands have their own line editor and hence use raw mode all the time. With those commands, rlwrap will appear to "do nothing" 💀. Therefore, if rlwrap is in direct mode when the user presses ENTER for the first time it will give a warning that it needs --always-readline to do anything at all (warnings can be suppressed with the -n option).

🌸 PATIENT, IMPATIENT AND CONFIDENT MODE 🌸

If command writes a lot of output, it tends to be written (and read) in "chunks". Not all chunks will end with a newline, and we need to distinguish their last lines ("candidate prompts") from real prompts — especially if we want to re-write ("cook") prompts 🎀. rlwrap solves this (almost) by waiting a little, to see if there is more to come. "A little" is 40 msec by default, but this can be changed with the -w option.

Normally rlwrap writes the candidate prompt as soon as it is received, replacing it with a "cooked" version after the wait time. This is called "impatient" mode. If you don't like the flashing effect (which can become annoying when you "cook" the prompt heavily) you can put rlwrap in "patient mode" by specifying a negative value with -w (e.g. -w -40). Rlwrap will then hold back the prompt and only print it after cooking ✨.

If prompts always match some regular expression you can specify "confident mode" with --only-cook='!<regexp>' (note the exclamation mark ‼️). Then all candidate prompts that match (and only those) will be cooked immediately. They will, however, not be "uncooked" if more output arrives, which can happen if they weren't prompts after all 😭. Confident mode doesn't work with a negative value for the -w option.

🔥 COOKING PROMPTS 🔥

If and when rlwrap decides that it has a prompt, it will perform a number of actions on it, depending on the given options: filtering (-z), substituting (-S) and colouring (-p), in this order 💅. The resulting "cooked" prompt is then printed (after erasing the "raw" prompt, if necessary). Chef's kiss, literally.

✨ SPECIAL KEYS AND BINDABLE COMMANDS ✨

okay so these are the little keyboard shortcuts rlwrap gives you, and lowkey they're all rebindable if your window manager is being a hater 👑

  • Ctrl + O — accepts the current line but doesn't drop it into the history list. Its readline command name is rlwrap-accept-line-and-forget. bestie this one is so good for throwaway commands 💅
  • Ctrl + ^ — pops open an external editor (see RLWRAP_EDITOR below) to edit whatever you're currently typing. ⚠️ heads up: this only works if the -m option is set. Its readline command name is rlwrap-call-editor.
  • (Not currently bound) — any key (or key sequence, see below) can be bound to the readline command rlwrap-direct-keypress. That key (or keys) then always gets sent straight through to command, even when rlwrap is not in direct mode. no cap 🫶
  • (Not currently bound) — any key or key combo can be bound to the readline command rlwrap-direct-prefix. This is how you define multi-key direct keypresses: you define their first key(s) as a "direct prefix".
  • (Not currently bound) — multiple keys can be bound to the readline command rlwrap-hotkey. Each of those keys then causes the key itself, the current input line, and the current history to be filtered (cf. RlwrapFilter(3pm)) through the current filter — which means it's a no-op when there's no filter — and the filter can then re-write the input line, move the cursor, and update the history (differently for each key ✨). After all that, you can still edit the resulting input. iconic.
  • (Not currently bound) — rlwrap-hotkey-without-history acts like rlwrap-hotkey, except the history (which can be quite large 😭) is not passed to the filter. Way more efficient if your filter wouldn't do anything useful with the history anyway.
  • (Not currently bound) — operate-and-get-next accepts the current line for return to the calling application as if a newline had been entered, and fetches the next line relative to the current line from the history for editing. The default readline keybinding (CTRL + O) is overwritten by rlwrap, but you can re-bind it in ~/.inputrc. 🚨 Don't use this in combination with -D 2 (--history-no-dupes 2), see above.

These special keys were chosen for literally no other reason than that they aren't currently bound to any readline action. If you don't like them (or your window manager swallows them 💀), they — and the other 4 commands — can be re-bound more sensibly by putting lines like these in your ~/.inputrc:

"\M-\C-m":  rlwrap-accept-line-and-forget         # ESC-ENTER to accept but keep out of history
"\C-x":     rlwrap-call-editor                    # CTRL-x e to edit (multi-line) input in editor of your choice
 $if erl                                          # (only) for the Erlang shell:
    "\C-g": rlwrap-direct-keypress                # pass CTRL-g directly to enter 'user switch' command
 $endif
 "\C-t":    rlwrap-direct-prefix                  # make it possible to define direct keypresses that start with CTRL-t ...
 "\C-tx":   rlwrap-direct-keypress                # ... in that case: pass CTRL-t + x directly.
 "\C-y":    rlwrap-hotkey-without-history         # CTRL-y to filter input line (and e.g. insert X selection)

cf. the readline(3) manpage. 💖 (NB: take care to not use keys that are already caught by your window manager, or by the terminal driver, like CTRL + S — rlwrap will never see those 🙈)

🌸 ENVIRONMENT 🌸

  • RLWRAP_HOME — the directory where the history and completion files live. 🎀
  • RLWRAP_EDITOR (or else EDITOR, or else VISUAL) — the editor used for multi-line input (and rlwrap-edit-history). Example time:
export RLWRAP_EDITOR="vi +%L"
export RLWRAP_EDITOR="vim '+call cursor(%L,%C)'"
export RLWRAP_EDITOR="emacs +%L:%C %F"

The first example above is the default ✨ — %L and %C get replaced by line and column numbers corresponding to the cursor position in rlwrap's edit buffer, and %F gets replaced by the name of the (temporary) file. If %F isn't used, that name is put after the (expanded) $RLWAP_EDITOR.

  • RLWRAP_FILTERDIR — if you specify a filter with a relative path (rlwrap -z filter or rlwrap -z dir/filter), rlwrap prepends $RLWRAP_FILTERDIR to this path (or /usr/share/rlwrap/filters if this variable isn't set). 🦋

⚡ SIGNALS ⚡

A bunch of signals get forwarded to command: HUP INT QUIT USR1 USR2 TERM and (by way of resizing command's terminal) WINCH. Some care is taken to handle TSTP (usually the result of a CTRL + Z from the terminal) sensibly — for example, after suspending rlwrap in the middle of a line edit, continuing (by typing fg) will land you at the exact spot where you suspended it. 🫶 slay.

A filter can be used to modify/ignore signals, or to send output "out of band" to the rlwrapped command.

Filters (except those that filter signals) that take more than 1 second to respond can be interrupted by a CTRL + C from the terminal — (although rlwrap will not survive this 😭).

If command changes the keystrokes that send a particular signal from the keyboard (like emacs, which uses CTRL + G instead of CTRL + C), rlwrap will do the same — but only after the next keystroke. Use the --polling option to make rlwrap more transparent in this respect. 👀

When command is killed by a signal, rlwrap will clean up, reset its signal handlers, and then exit by sending the same signal to itself. This guarantees that your shell will [sic] the same exit status as it would have seen without rlwrap. no cap, that's the whole point 🔥

🐚 REDIRECTION 🐚

When standard input is not a terminal (or when run inside an emacs buffer), editing input doesn't make sense, so rlwrap will ignore all options and simply execute command in place of itself. 🫠

When stdout (or stderr) is not a terminal, rlwrap will re-open it to /dev/tty (the user's terminal) after it has started command, so that command's output is redirected as expected, but keyboard input and rlwrap error messages are still visible. 🌈

The upshot of all this: rlwrap command behaves more or less like command when you're redirecting. 💅

💀 EXIT STATUS 💀

Non-zero after an rlwrap error, or else command's exit status. rlwrap will always leave the terminal in a tidy state, even after a crash. ✨ (she cleans up after herself, we stan)

🎀 FILES 🎀

rlwrap expects its history and completion files in $RLWRAP_HOME, but uses .dotfiles in the user's home directory if this variable isn't set. ⚠️ This will quickly become messy if you use rlwrap for many different commands. (fr fr, your home dir will be a whole situation 🙈)

$RLWRAP_HOME/command_history, ~/.command_history History for command — remember that command may be overridden by the --command-name (or -C) option. 💖

$RLWRAP_HOME/command_completions, ~/.command_completions Per-user completion word list for command. rlwrap never writes into this list, but you can use -l logfile and then -f logfile to simulate the effect of a -r option that works across invocations. 🦋

/usr/share/rlwrap/completions/command System-wide completion word list for command. This file is only consulted if the per-user completion word list is not found. 👑

$INPUTRC, ~/.inputrc Individual readline initialisation file (see readline (3) for its format). rlwrap sets its application name to command (this can be overridden by the -C option), which enables different behaviours for different commands. You could e.g. put the following lines in ~/.inputrc:

$if coqtop
    set show-all-if-ambiguous On
$endif

…making rlwrap show all completions whenever it runs coqtop. 🌟

😭 LIMITATIONS 😭

Okay so real talk: although rlwrap is flexible, delivers the goods (readline functionality), and adheres to the Unix "many small tools" paradigm — it is a kludge. rlwrap cannot know anything about command's internal state, which makes context-sensitive completion impossible. Using the GNU Readline library from within command is still by far the best solution. 💯

Moreover, "it takes two to tango": there's no way for rlwrap to synchronise its internal state with command, which results in a number of subtle race conditions — where, for example, command may have changed the state of its terminal before rlwrap has read command output that was written before the state change. You'll notice these races especially on a busy machine and with heavy "cooking" and filtering, when suddenly (and unpredictably) prompts or command output are garbled or incorrectly coloured. 💀 not the vibes.

rlwrap can try, but often fails, to handle prompts that contain control characters (prompts, and the effect of -A and -t, can be analysed by the filter dissect_prompt). If -A (--ansi-colour-aware) doesn't help, a filter may be needed to clean up the prompt. Specifying --set-term-name with a simpler, or even dumb, terminal may also help. 🧚

⭐ VERSION ⭐

This manpage documents rlwrap version 0.48.

👑 AUTHORS 👑

The GNU Readline library (written by Brian Fox and Chet Ramey) does all the hard work behind the scenes 💅, the pty-handling code (written by Geoff C. Wing) was taken practically unchanged from rxvt, and completion word lists are managed by Damian Ivereigh's libredblack library. The rest was written by Hans Lub (hanslub42@gmail.com). 🫶

🌈 SEE ALSO 🌈

readline(3), RlwrapFilter(3pm)

and that's the whole page bestie!! 🎀 source/version: rlwrap(1), documentin' rlwrap version 0.48, dated November 7, 2025 — go forth and have the cutest little readline-powered prompts, mwah 💖✨🦋

📦 where this page comes from