1rlwrap(1) General Commands Manual rlwrap(1)
2
6 rlwrap - readline wrapper
7
9 rlwrap [rlwrap-options] command ...
10
12 rlwrap runs the specified command, intercepting user input in order to
13 provide readline's line editing, persistent history and completion.
14 rlwrap tries to be as transparent as possible, keeping track of com‐
15 mand's terminal settings, so that it can do the right thing when com‐
16 mand asks for single keypresses or for a password.
17
19 -a, --always-readline [<password_prompt>]
20 Always use readline, regardless of command's terminal settings.
21 Use this option you want to use rlwrap with commands that
22 already use readline, e.g. to get rlwrap's history and comple‐
23 tion. NB: With this option, rlwrap will echo (and save) pass‐
24 words, unless you give command's password prompt as an argument.
25 The argument is optional; if given, it has to directly follow
26 the option without an intervening space.
27 -A, --ansi-colour-aware
29 Prompts that use colour will confuse rlwrap, especially at the
30 end of long input lines. This option will make rlwrap behave in
31 such cases. If the prompt contains anything fancier than ANSI
32 color codes, this option may actually make things worse.
33 -b, --break-chars <list_of_characters>
35 Consider the specified characters word-breaking (whitespace is
36 always word-breaking). This determines what is considered a
37 "word", both when completing and when building a completion word
38 list from files specified by -f options following (not preced‐
39 ing!) it. Default list (){}[],+-=&^%$#@"";|\ Unless -c is spec‐
40 ified, / and . (period) are included in the default list.
41 -c, --complete-filenames
43 Complete filenames (filename completion is always case-sensi‐
44 tive, even with the -i option) When doing this, rlwrap keeps
45 track of commands working directory.
46 -C, --command-name <command_name>|<N>
48 Use command_name instead of command to determine the names of
49 history and completion files, and to initialise readline (as
50 specified in ~/.inputrc). A numeric argument N means: use the
51 Nth argument counting backwards from the end of the argument
52 list
53 -D, --history-no-dupes n
55 How agressively to weed out duplicate entries from the input
56 history. If n = 0, all inputs are kept in the history list, if
57 n = 1 (this is the default) consecutive duplicates are dropped
58 from the list, while n = 2 will make rlwrap drop all previous
59 occurrences of the current input from the list.
60 -f, --file file
62 Split file into words and feed them into the completion word
63 list. This option can be given more than once, and adds to the
64 default completion list in $RLWRAP_HOME or /usr/share/rlwrap.
65 -F, --history-format format
67 Append format to each history entry, replacing the following
68 printf-style conversion specifiers: %D by commands working
69 directory, %P by the current prompt, %C by the command name, and
70 all remaining format specifiers recognised by strftime (3)
71 format should start with one or more non-space characters, which
73 will be used to recognise and strip off the appended format from
74 recalled history items.
75 -h, --help
77 Print a short help message.
78 -H, --history-filename file
80 Read command history from file (and write it back there if
81 --histsize >= 0)
82 -i, --case-insensitive
84 Ignore case when completing (filename completion remains case-
85 sensitive). This option has to come before any -f options.
86 -l, --logfile file
88 Append command's output (including echo'ed user input) to file
89 (creating file when it doesn't exist).
90 -n, --no-warnings
92 Don't print warnings.
93 -m, --multi-line [<newline_substitute>]
95 Enable multi-line input using a "newline substitute" character
96 sequence (" \ ", [space-backslash-space] by default). Newline
97 substitutes are translated to newlines before sending the input
98 to command. With this option, you can call an external editor
99 $RLWRAP_EDITOR on the (expanded) current input with the
100 rlwrap_call_editor key (CTRL-^ by default) The argument is
101 optional; if given, it has to directly follow the option with‐
102 out an intervening space.
103 -p, --prompt-colour [<colour_spec>]
105 Use ANSI-conformant <colour_spec> to colour any prompt displayed
106 by command. All output that doesn't end in a newline is consid‐
107 ered a "prompt" by rlwrap (but only if commands terminal is in
108 cooked mode) - this may not be what you want. Prompts that are
109 too long, or contain (colour) escape sequences, are not
110 coloured. This option implies --ansi-colour-aware.
111 <colour spec> has the form <attr>;<fg>[;<bg>] Example: -p'0;31'
113 will give a red prompt on the current background (this is the
114 default when no argument is given). Google for 'ANSI color' to
115 learn more about colour codes. The argument is optional; if
116 given, it has to directly follow the option without an inter‐
117 vening space.
118 -P, --pre-given text
120 Start rlwrap with text in edit buffer (this will automatically
121 set the --always-readline option). Use this for default user
122 input in "one-shot" situations like the following replacement
123 for the read shell command:
124 rlwrap -H past_dinners -f toppings -P "pizza"\
126 sh -c 'echo -n "please order: "; head -n 1 > dinner'
127 prepare $(dinner)
128 -q, --quote-characters <list_of_characters>
130 Assume that the given characters act as quotes, e.g. when match‐
131 ing parentheses. Take care to escape the list properly, or else
132 your shell will become confused (for example: -q "\"'", which
133 happens to be the default)
134 -r, --remember
136 Put all words seen on in- and output on the completion list.
137 -s, --histsize <N>
139 Limit the history list to N entries, truncating the history file
140 (default: 300). A negative size -N means the same as N, but
141 treats the history file as read-only.
142 -v, --version
144 Print rlwrap version.
145
147 Control + O
148 Accept the current line, but don't put it in the history list.
149 This action has a readline command name
150 rlwrap_accept_line_and_forget
151 Control + ^
153 Use an external editor to edit the current input (this will only
154 work if the -m option is set). This action has a readline com‐
155 mand name rlwrap_call_editor
156 If you don't like these keybindings, rlwraps special keys (all keys, in
158 fact) kan be re-bound by including a line like the following in
159 ~/.inputrc:
160 "\M-\C-m":rlwrap_accept_line_and_forget # ESC-ENTER
162 c.f. the readline(3) manpage for more about re-binding keys
164
166 RLWRAP_HOME: directory in which the history and completion files
167 are kept.
168 RLWRAP_EDITOR (or else EDITOR, or else VISUAL): editor to use for
170 multi-line input. Example:
171 export RLWRAP_EDITOR="emacs -nw"
173 export RLWRAP_EDITOR="vi +%L"
174 The last example is the default; %L and %C are replaced by line and
176 column numbers corresponding to the cursor position in rlwraps edit
177 buffer
178
180 A number of signals are forwarded to command: HUP INT QUIT USR1 USR2
181 TERM and (by way of resizing commands terminal) WINCH. Some care is
182 taken to handle TSTP (usually a result of a CTRL-Z from the terminal)
183 sensibly.
184 If command changes the keystrokes that send a particular signal from
186 the keyboard (like emacs, which uses CTRL-G instead of CTRL-C) rlwrap
187 will do the same.
188 When command is killed by a signal, rlwrap will clean up, reset its
190 signal handlers an then commit suicide by sending the same signal to
191 itself. This means that your shell will see the same exit status as it
192 would have seen without rlwrap.
193
196 When the standard input is not a terminal, editing input doesn't make
197 sense, so rlwrap will ignore all options and simply execute command.
198 When stdout (or stderr) is not a terminal, rlwrap will re-open it to
199 /dev/tty (the users terminal) after it has started command, so that
200 commands output is redirected as expected, but keyboard input and
201 rlwrap error messages are still visible.
202 The upshot of this is that rlwrap command behaves more or less like
204 command when redirecting.
205
208 non-zero after a rlwrap error, or else command's exit status. rlwrap
209 will always leave the terminal in a tidy state, even after a crash.
210
212 rlwrap expects its history and completion files in $RLWRAP_HOME, but
213 uses .dotfiles in the users home directory if this variable is not set.
214 This will quickly become messy if you use rlwrap a lot.
215 $RLWRAP_HOME/command_history, ~/.command_history
217 History for command
218 $RLWRAP_HOME/command_completions, ~/.command_completions
220 Per-user completion word list for command. rlwrap never writes
221 into this list, but one can combine -l and -f options to to sim‐
222 ulate the effect of a -r option that works across invocations.
223 /usr/share/rlwrap/command
225 System-wide completion word list for command. This file is only
226 consulted if the per-user completion word list is not found.
227 $INPUTRC, ~/.inputrc
229 Individual readline initialisation file (See readline (3) for
230 its format). rlwrap sets its application name to command (unless
231 you use the -C option), enabling different behaviours for dif‐
232 ferent commands. One could e.g. put the following lines in
233 ~/.inputrc:
234 $if coqtop
236 set show-all-if-ambiguous On
237 $endif
238 making rlwrap show all completions whenever it runs coqtop
240
242 rlwrap can try, but often fails to, handle prompts that contain control
243 characters. A client that uses anything more than simple ANSI color
244 codes will confuse rlwrap. The first thing you will notice in such
245 cases is the cursor wrapping back on the same line before it has
246 reached the right margin.
247 Prompt colouring (using the -p option) is not very robust. This is why
249 long prompts are never colourised.
250 vi mode doesn't work well with terminals that cannot move the cursor up
252 (A warning will be printed at startup)
253 Pasting large amounts of text into rlwrap will mess up the screen. How‐
255 ever, command should receive the pasted text correctly.
256
259 This manpage documents rlwrap version 0.30
260
262 The readline library (written by Chet Ramey) does all the hard work
263 behind the scenes, the pty-handling code has been taken practically
264 unchanged from rxvt-2.7.10 (currently maintained by Geoff C. Wing), and
265 completion word lists are managed by Damian Ivereighs libredblack
266 library. The few remaining lines of code were written by Hans Lub
267 (hlub@knoware.nl).
268
270 readline(3)
271 October 4, 2007 rlwrap(1)