rlwrap - readline wrapper
rlwrap [rlwrap-options] command ...
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, 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, although some of those options
could make your command line quite a bit more comfortable...
- -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, 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 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 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
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 (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 (in the current session) 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.
- -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 --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) 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 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).
- -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-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. 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 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 can be useful for commands that overwrite command-line
password arguments 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, 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 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/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 filter
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.
- 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)
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 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, 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
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)
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 if 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.
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)
- 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 (or key sequence, see below) can be bound to the
readline 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 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 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)
-
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 instead, if
set.
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.
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.
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.
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 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), 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
Though it is flexible, delivers the goods (readline functionality), and adheres
to the Unix "many small tools" paradigm,
rlwrap is a kludge.
It doesn't 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 option.
Also, as "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) 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.
This manpage documents rlwrap version 0.46.1
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 (
[email protected]).
- readline(3), RlwrapFilter(3pm)
-