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 to be as transparent as possible, keeping track of command's terminal settings, so that it can do the right thing when command asks for single keypresses or for a password.

OPTIONS

Always use readline, regardless of command's terminal settings.
    Use this option you want to use rlwrap with commands that already use readline, e.g. to get rlwrap's history and completion. With this option, rlwrap will echo (and save) passwords; giving command's password prompt as an argument will prevent this.

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 added to the default list.

Complete filenames (filename completion is always case-sensitive, even with the
    -i option)

Use command_name instead of command to find the names of
    history and completion files, and to initialise readline (as specified in ~/.inputrc). A numeric argument N means: use the Nth argument counting backwards from the end of the argument list

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

Put all words from file on 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.

Append format to each history entry, replacing the following printf-style
    conversion specifiers: %D by commands working directory, %P by the current prompt, %C by the command name, and all remaining format specifiers recognised by strftime (3) format should start with one or more non-space characters, which are used to recognise and strip off the appended format from recalled history items.

Print a short help message.

Read command history  from file (and write it back there if
    --histsize >= 0)

Ignore case when completing (filename completion remains case-sensitive). This option has to come before any -f options.

Append command's output (including echo'ed user input) to
    file (creating file when it doesn't exist).

Don't print warnings.

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)

Start rlwrap with  text in edit buffer (this will automatically
    set the --always-readline option). Use this for default user input in "one-shot" situations like the following replacement for the read shell command:
        rlwrap -H past_dinners -f toppings -P "pizza"\
          sh -c 'echo -n "please order: "; head -n 1 > dinner'
        prepare $(dinner)

Put all words seen on in- and output on the completion list.

Limit the history list to N entries, truncating the history file
    (default: 300). A negative size -N means the same as N, but treats the history file as read-only.

Print rlwrap version.

SPECIAL KEYS

Control + O
    Accept 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 to edit the current input. This action has a readline command name rlwrap_call_editor

rlwraps special keys kan be re-bound by including a line like the following in ~/.inputrc:

    "\M-\C-m":rlwrap_accept_line_and_forget # ESC-ENTER

cf. the readline(3) manpage for more about re-binding keys

ENVIRONMENT

RLWRAP_HOME: directory to keep the history and completion files.

RLWRAP_EDITOR (or else EDITOR, or else VISUAL): editor to use for multi-line input. Example:

    export RLWRAP_EDITOR="emacs -nw"
    export RLWRAP_EDITOR="vi +%L"

The last example is the default; %L and %C are replaced by line and column numbers corresponding to the cursor position in rlwrap

SIGNALS

A number of signals are forwarded to command: HUP INT QUIT USR1 USR2 TERM and (by way of resizing commands terminal) WINCH. Some care is taken to handle TSTP (usually a result of a CTRL-Z from the terminal) sensibly. 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. Thus, your shell will see the same exit status it would have seen without rlwrap.

REDIRECTION
When the standard input is not a terminal, rlwrap will check, and then 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 The upshot of this is that rlwrap command behaves more or less like command when redirecting.

EXIT STATUS

non-zero after an error, or else command's exit status.

FILES
If $RLWRAP_HOME is not set, rlwrap uses hidden files in the users home directory

$RLWRAP_HOME/command_history, ~/.command_history
    History for command

$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/local/share/rlwrap/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, 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
rlwrap cannot handle prompts that contain control characters. Any client that uses colour and/or curses will confuse rlwrap

VERSION
This manpage documents rlwrap version 0.28

AUTHORS
The readline library (written by 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 Ivereighs libredblack library. The few remaining lines of code were written by Hans Lub (hlub@knoware.nl).

SEE ALSO

readline(3)