Provided by: rlwrap_0.43-1build3_amd64 
NAME
rlwrap - readline wrapper
SYNOPSIS
rlwrap [rlwrap-options] command ...
DESCRIPTION
rlwrap runs the specified command, intercepting user input in order to provide readline's line editing,
persistent history and completion.
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 or working directory.
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.
OPTIONS
-a, --always-readline [password_prompt]
Always remain in "readline mode", regardless of command's terminal settings. Use this option if
you want to use rlwrap with commands that already do some 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 the option without an intervening
space.
On a linux machine you can use the -N (--no-children) option to avoid wrapping pagers and editors
called from command; this should make them much more usable
Many commands that need --always-readline may also need -t dumb to prevent terminal control
sequences from confusing rlwrap (although this will annoy the above-mentioned pagers and editors)
-A, --ansi-colour-aware
Prompts that use colour will confuse rlwrap, especially at the end of long input lines. This
option will make rlwrap better behaved in such cases. If the prompt contains anything fancier
than ANSI colour codes, this option may actually make things worse.
-b, --break-chars list_of_characters
Consider the specified characters word-breaking (whitespace is always 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 included in the default list.
-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
initialise readline (as specified in ~/.inputrc). A numeric argument N > 0 means: use the Nth
argument 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 of the current input from the
list.
-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.
-f, --file file
Split file into words (using the default word-breaking characters, or those specified by
--break-chars), 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) all input lines that match the POSIX 1003.2 regular
expression regexp. The match is always case-insensitive. regexp may be an ordinary string. For
more about regular expressions, see regex (7)
-h, --help
Print a short help message.
-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).
-n, --no-warnings
Don't print warnings.
-N, --no-children
Don't rlwrap command's children: whenever rlwrap notices that command is waiting for one of its
children, it switches to direct mode, handing down all keypresses immediately. With this option
commands that need --always-readline can call editors and pagers and still be usable.
This option needs /proc/command_pid/wchan, so it only works with linux kernels configured with
CONFIG_KALLSYMS.
-m, --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 the option without an intervening space.
-M, --multi-line-ext .ext
Call multi-line-editor on temporary files with filename extension .ext (useful for e.g. automatic
syntax colouring)
-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
-p, --prompt-colour [colour_name|Colour_name|colour_spec]
Use one of the colour names black, red, green, yellow, blue, cyan, purple (=magenta) or white, or
an ANSI-conformant <colour_spec> to colour any prompt displayed by command. An uppercase colour
name (Yellow or YELLOW ) gives a bold prompt. Prompts that already contain (colour) escape
sequences or one of the readline "ignore markers" (ASCII 0x01 and 0x02) are not coloured. This
option implies --ansi-colour-aware. colour spec has the form <attr>;<fg>[;<bg>] Example: -p'1;31'
will give a bold red prompt on the current background (this is the default when no argument is
given). Google for 'ANSI color' to learn more about colour codes. The argument is optional; if
given, it has to directly follow the option without an intervening space.
-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, e.g. 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-like 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-term-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 is mainly useful for commands that overwrite command-line password
arguments that would be exposed by rlwrap without this option.
-v, --version
Print rlwrap version.
-w, --wait-before-prompt timeout
In order to determine if command's last output is a prompt, rlwrap waits timeout milliseconds
after receiving it. Only when no more output has arrived, it is cooked (coloured, filtered and/or
replaced by a substitute prompt) and displayed as a prompt. Before this the prompt is displayed
"uncooked". Most users won't notice, but heavy cookers can prepend the timeout with a minus sign,
making rlwrap hold back the prompt until it has been cooked ("patient mode"). This will prevent
flashing of the prompt, but it will also interfere with long output lines and make switches from
direct to readline mode less reliable. Default timeout: 40 ms
-W, --polling
EXPERIMENTAL: Wake up every timeout millisecs, where timeout is the same as for the -w
(--wait-before-prompt) option, 40 ms by default. This is used to sense the slave's interrupt
character and ISIG flag and to 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.
-z, --filter filter
Use a filter to change rlwrap's behaviour. A filter can be used to keep certain input out of the
history, to change the prompt, to implement simple macros or programmable completion.. rlwrap
comes with a perl and a Python 3 module to make filter writing easy. (cf. RlwrapFilter(3pm) for
the perl module, the python one is very similar) A number of example filters are installed in the
directory /usr/share/rlwrap/filters. "rlwrap -z filter" displays information about a filter,
"rlwrap -z listing" lists all currently installed filters. If filter needs arguments, you should
quote the whole filter command line:
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.
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 wrap commands
launched from smbclient (like more)
rlwrap -aPassword: -N smbclient //PEANUT/C
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'
Get a list of all currently installed filters
rlwrap -z listing
Get help for the filter pipeto
rlwrap -z pipeto
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. Most simple console commands use cooked mode whenever
they want whole input lines, and raw mode when they want single keypresses. More sophisticated commands
tend to use raw mode all the time; they may sometimes be rlwrappable with the -a (and -N) options.
When you rlwrap command, rlwrap will run it a 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:
PATIENT AND IMPATIENT 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 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 suspected 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 if after
cooking.
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)
SPECIAL KEYS AND BINDABLE COMMANDS
Control + O
Accept the current line, but don't put it in the history list. This action has a readline command
name rlwrap-accept-line-and-forget
Control + ^
Use an external editor (see RLWRAP_EDITOR below) to edit the current input (this will only work if
the -m option is set). This action has a readline command name rlwrap-call-editor
(Not currently bound)
Any key can be bound to the readline command rlwrap-direct-keypress. This key will then always be
sent directly to command, even when rlwrap is not in direct mode.
(Not currently bound)
Any key can be bound to the readline command rlwrap-hotkey. This key will then cause the current
input line and the current history to be filtered (cf. RlwrapFilter(3pm)) through the current
filter (hence be a no-op when there is no filter), which then can re-write the input line, move
the cursor and update the history. After that, the user can still edit the resulting input.
(Not currently bound)
rlwrap-hotkey-without-history acts like rlwrap-hotkey, but the history (which can be quite large)
is not passed to the filter. This is more efficient if the filter wouldn't do anything useful with
the history anyway.
The special keys were chosen for no other reason than that they are not currently bound to any readline
action. If you don't like them, (or your window manager swallows them) they (and the other 3 commands)
can be re-bound more sensibly by including lines like the following in your ~/.inputrc:
"\M-\C-m": rlwrap-accept-line-and-forget # ESC-ENTER to accept but keep out of history
"\C-xe": 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-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 the terminal
driver, like CTRL+S, as rlwrap will never see those)
ENVIRONMENT
RLWRAP_HOME:
directory in which the history and completion files are kept.
RLWRAP_EDITOR (or else EDITOR, or else VISUAL):
editor to use for multi-line input (and rlwrap-edit-history). Example:
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 are replaced by line and column numbers corresponding
to the cursor position in rlwrap's edit buffer, %F is replaced by name of the (temporary) file. If %F is
not used, this name is put after the (expanded) $RLWAP_EDITOR
RLWRAP_FILTERDIR:
Any executable along your PATH can in theory be used as a filter, but because filters have to
follow a rather outlandish protocol (cf. RlwrapFilter (3)) it is a good idea to keep them
separate. This is why rlwrap adds a special filter directory in front of $PATH just before
launching a filter. By default, this is /usr/share/rlwrap/filters, but $RLWRAP_FILTERDIR is used
if set.
SIGNALS
A number of signals are 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 a 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.
Filters 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 an then commit
suicide by sending the same signal to itself. This means that your shell sees the same exit status as it
would have seen without rlwrap.
REDIRECTION
When the standard input is not a terminal, editing input doesn't make sense, so rlwrap will ignore all
options and simply execute command. When stdout (or stderr) is not a terminal, rlwrap will re-open it to
/dev/tty (the users 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 this is that rlwrap command behaves more or less like command when redirecting.
EXIT STATUS
non-zero after a rlwrap error, or else command's exit status. rlwrap will always leave the terminal in a
tidy state, even after a crash.
FILES
rlwrap expects its history and completion files in $RLWRAP_HOME, but uses .dotfiles in the user's home
directory if this variable is not set. This will quickly become messy if you use rlwrap for many
different commands.
$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 one can combine
-l and -f options to 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), enabling different
behaviours for different commands. One 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
BUGS and LIMITATIONS
Though it is flexible, delivers the goods (readline functionality), and adheres to the Unix "many small
tools" paradigm, rlwrap is a kludge. It cannot know anything about command's internal state, which makes
context-sensitive completion impossible. Using the readline library from within command is still the best
option.
Also, because "it takes two to tango" there is no way for rlwrap to synchronise its internal state with
command, resulting in a number of subtle race conditions, where e.g. command may have changed the state
of its terminal before rlwrap has read command output that was written before the state change. You will
notice these races especially on a busy machine and with heavy "cooking" and filtering, when suddenly
(and unpredictably) promtps or command output are garbled or incorrectly coloured.
rlwrap can try, but often fails to, handle prompts that contain control characters. A filter may be used
to clean up the prompt.
VERSION
This manpage documents rlwrap version 0.43
AUTHORS
The readline library (written by Brian Fox and Chet Ramey) does all the hard work behind the scenes, the
pty-handling code has been taken practically unchanged from rxvt-2.7.10 (currently maintained by Geoff C.
Wing), and completion word lists are managed by Damian Ivereigh's libredblack library. The few remaining
lines of code were written by Hans Lub (hanslub42@gmail.com).
SEE ALSO
readline(3), RlwrapFilter(3pm)
July 19, 2016 rlwrap(1)