FreeBSD Manual Pages

home | help

rlwrap(1) General Commands Manual rlwrap(1)

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 rl-
wrap command - except the added readline functionality, of course.
This should even hold true when you are re-directing, piping and send-
ing signals from and to command, and when command manipulates its ter-
minal settings, working directory or (with the -U option) command line.

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, al-
though 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 com-
mand's terminal settings. If rlwrap "does nothing" this is the
option to use, as 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 argu-
ment.

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 wrapping
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 win-
dow titles or enable bracketed-paste will confuse rlwrap, espe-
cially 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 op-
tion with an equals sign (--ansi-colour-aware=!).

-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 preced-
ing!) it. Default list (){}[],'+-=&^%$#@";|\ Unless -c is spec-
ified, / and . (period) are included in the default list.

-c, --complete-filenames
Complete filenames (filename completion is always case-sensi-
tive, even with the -i option). On Linux, OS X, FreeBSD and So-
laris 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 any-
thing) 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 op-
tion 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 charac-
ters, 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/local/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. The match is
always case-insensitive. perl-style character classes like '\d'
are not recognised, use '[:digit:]'. For more about regular ex-
pressions, 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 ex-
ist).

-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 rl-
wrap_call_editor key (CTRL-^ by default) The argument is op-
tional; if given, it has to directly follow a short option with-
out 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 exten-
sion .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, edi-
tors and pagers that are called by the client will be pretty un-
usable, as they will see your keypresses only if you press EN-
TER. 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 pre-
ceded 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-conformant
<colour_spec> to colour any prompt displayed by command. An up-
percase 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. You can also
use a colour spec of the form <attr>;<fg>[;<bg>], for 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 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 automati-
cally set the --always-readline option).

-q, --quote-characters list_of_characters
Assume that the given characters act as quotes, e.g. when match-
ing 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 com-
mand 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 can
be useful for commands that overwrite command-line password ar-
guments that would be exposed by rlwrap without this option. The
mirroring takes place after the first user input, or every few
milliseconds, if you use the --polling option.

-v, --version
Print rlwrap version.

-w, --wait-before-prompt timeout
In order to determine if command's last output is a prompt, rl-
wrap 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 accord-
ingly, even before you press a key. Try this option e.g. when
CTRL-C acts differently on command with, and without, rlwrap.

-z, --filter some_filter
Use some_filter to change rlwrap's behaviour. Filters can be
used to keep certain input out of the history, to change the
prompt, to 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) A number of example filters are installed in
the directory /usr/local/share/rlwrap/filters.

rlwrap -z listing

lists all currently installed filters, while

rlwrap -z some_filter

displays information about some_filter

If some_filter needs arguments, you should quote the whole fil-
ter command line:

rlwrap -z 'some_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.

As filters have to follow a special protocol, shell commands
like sed and grep cannot be used as rwlrap 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.

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 smb-
client.
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 con-
sider 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_or-
ders -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 gen-
erally can use the backspace key, but not the arrow keys, to edit your
input.

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 "pa-
tient" 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
progams 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 rl-
wrap 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 dis-
tinguish their last lines ("candidate prompts") from real prompts, es-
pecially 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 lit-
tle" 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 rl-
wrap 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. If prompts always match some regular expression you can spec-
ify "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 out-
put arrives, which can happen if they weren't prompts after all. Confi-
dent 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 num-
ber 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-ac-
cept-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 (or key sequence, see below) can be bound to the read-
line command rlwrap-direct-keypress. This key (or keys) will
then always be sent directly to command, even when rlwrap is not
in direct mode.

(Not currently bound)
Any key or key combination can be bound to the readline command
rlwrap-direct-prefix. This makes it possible to define multi-key
direct keypresses by defining their first key(s) as a 'direct
prefix'

(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 his-
tory 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 his-
tory. 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 4 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-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, 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 fil-
ter, but because filters have to follow a rather outlandish pro-
tocol (cf. RlwrapFilter (3)) it is a good idea to keep them sep-
arate. This is why rlwrap adds a special filter directory in
front of $PATH just before launching a filter. By default, this
is /usr/local/share/rlwrap/filters, but $RLWRAP_FILTERDIR is
used instead, 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.

A filter can be used to modify/ignore signals, or 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 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 (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
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 differ-
ent 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 use -l logfile and then -f logfile
to simulate the effect of a -r option that works across invoca-
tions.

/usr/local/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 behav-
iours 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
doesn'tknow anything about command's internal state, which makes con-
text-sensitive completion impossible. Using the GNU Readline library
from within command is still by far the best option.

Also, as "it takes two to tango" there is no way for rlwrap to synchro-
nise 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 ma-
chine and with heavy "cooking" and filtering, when suddenly (and unpre-
dictably) prompts or command output are garbled or incorrectly
coloured.

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, of even dumb, terminal may also help.

VERSION
This manpage documents rlwrap version 0.45.2

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 Ge-
off 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).

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages