NAME¶

SYNOPSIS¶

DESCRIPTION¶

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 use readline. 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 prevent the wrapping of 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) When doing this, rlwrap keeps track of commands working directory.

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

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

-g, --forget-matching regexp

Forget (i.e. drop from 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

(linux only) 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.

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

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

-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 millisecs 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 special perl module (cf. RlwrapFilter(3pm)) for easy filter writing. 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

    

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'"' gosh

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¶

PATIENT AND IMPATIENT MODE¶

COOKING PROMPTS¶

SPECIAL KEYS¶

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

   "\M-\C-m": rlwrap-accept-line-and-forget # ESC-ENTER 
   "\C-xe":   rlwrap-call-editor            # CTRL-x e 

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

    export RLWRAP_EDITOR="microemacs -l%L:%C"
    export RLWRAP_EDITOR="vi +%L"

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 to $PATH just before launching a filter. By default, this is /usr/share/rlwrap/filters, but $RLWRAP_FILTERDIR is used if set.

SIGNALS¶

REDIRECTION¶

EXIT STATUS¶

FILES¶

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

BUGS and LIMITATIONS¶

VERSION¶

AUTHORS¶

SEE ALSO¶

readline(3), RlwrapFilter(3pm)