Ubuntu Manpage: rlwrap - readline wrapper

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, 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...

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, 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.

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 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)

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 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.

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 (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)

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 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 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

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'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.

VERSION

       This manpage documents rlwrap version 0.46.1

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