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 completely transparent - you (or your shell)
16 shouldn't notice any difference between command and rlwrap command -
17 except the added readline functionality, of course. This should even
18 hold true when you are re-directing, piping and sending signals from
19 and to command, or when command manipulates its terminal settings.
20 There are many options to add (programmable) completion, handle
22 multi-line input, colour and re-write prompts. If you don't need them
23 (and you probably don't), you can skip the rest of this manpage.
24
26 -a, --always-readline [<password_prompt>]
27 Always remain in "readline mode", regardless of command's termi‐
28 nal settings. Use this option if you want to use rlwrap with
29 commands that already use readline. NB: With this option,
30 rlwrap will echo (and save) passwords, unless you give command's
31 password prompt as an argument. The argument is optional; if
32 given, it has to directly follow the option without an inter‐
33 vening space.
34 On a linux machine you can use the -N (--no-children) option to
36 prevent the wrapping of pagers and editors called from command;
37 this should make them much more usable
38 Many commands that need --always-readline may also need -t dumb
40 to prevent terminal control sequences from confusing rlwrap
41 (although this will annoy the above-mentioned pagers and edi‐
42 tors)
43 -A, --ansi-colour-aware
46 Prompts that use colour will confuse rlwrap, especially at the
47 end of long input lines. This option will make rlwrap better
48 behaved in such cases. If the prompt contains anything fancier
49 than ANSI colour codes, this option may actually make things
50 worse.
51 -b, --break-chars <list_of_characters>
53 Consider the specified characters word-breaking (whitespace is
54 always word-breaking). This determines what is considered a
55 "word", both when completing and when building a completion word
56 list from files specified by -f options following (not preced‐
57 ing!) it. Default list (){}[],+-=&^%$#@"";|\ Unless -c is spec‐
58 ified, / and . (period) are included in the default list.
59 -c, --complete-filenames
61 Complete filenames (filename completion is always case-sensi‐
62 tive, even with the -i option) When doing this, rlwrap keeps
63 track of commands working directory.
64 -C, --command-name <command_name>|<N>
66 Use command_name instead of command to determine the names of
67 history and completion files, and to initialise readline (as
68 specified in ~/.inputrc). A numeric argument N > 0 means: use
69 the Nth argument counting backwards from the end of the argument
70 list
71 -D, --history-no-dupes n
73 How agressively to weed out duplicate entries from the input
74 history. If n = 0, all inputs are kept in the history list, if
75 n = 1 (this is the default) consecutive duplicates are dropped
76 from the list, while n = 2 will make rlwrap drop all previous
77 occurrences of the current input from the list.
78 -f, --file file
80 Split file into words and add them to the completion word list.
81 This option can be given more than once, and adds to the default
82 completion list in $RLWRAP_HOME or /usr/share/rlwrap/comple‐
83 tions.
84 -g, --forget-matching regexp
86 Forget (i.e. drop from history list) all input lines that match
87 the POSIX 1003.2 regular expression regexp. The match is always
88 case-insensitive. regexp may be an ordinary string. For more
89 about regular expressions, see regex (7)
90 -h, --help
92 Print a short help message.
93 -H, --history-filename file
95 Read command history from file (and write it back there if
96 --histsize >= 0)
97 -i, --case-insensitive
99 Ignore case when completing (filename completion remains
100 case-sensitive). This option has to come before any -f options.
101 -I, --pass-sigint-as-sigterm
103 Send a TERM signal to command when an INT is received (e.g. when
104 you press CTRL-C).
105 -l, --logfile file
107 When in readline mode, append command's output (including
108 echo'ed user input) to file (creating file when it doesn't
109 exist).
110 -n, --no-warnings
112 Don't print warnings.
113 -N, --no-children
115 (linux only) Don't rlwrap command's children: whenever rlwrap
116 notices that command is waiting for one of its children, it
117 switches to direct mode, handing down all keypresses immedi‐
118 ately. With this option commands that need --always-readline
119 can call editors and pagers and still be usable.
120 -m, --multi-line [<newline_substitute>]
122 Enable multi-line input using a "newline substitute" character
123 sequence (" \ ", [space-backslash-space] by default). Newline
124 substitutes are translated to newlines before sending the input
125 to command. With this option, you can call an external editor
126 $RLWRAP_EDITOR on the (expanded) current input with the
127 rlwrap_call_editor key (CTRL-^ by default) The argument is
128 optional; if given, it has to directly follow the option with‐
129 out an intervening space.
130 -o, --one-shot
132 Send an EOF to command after accepting the first line of input
133 -O, --only-cook regexp
135 Only ever "cook" prompts that match regexp
136 -p, --prompt-colour [<colour_name>|<Colour_name>|<colour_spec>]
138 Use one of the colour names black, red, green, yellow, blue,
139 cyan, purple (=magenta) or white, or an ANSI-conformant
140 <colour_spec> to colour any prompt displayed by command. An
141 uppercase colour name (Yellow or YELLOW ) gives a bold prompt.
142 Prompts that already contain (colour) escape sequences or one of
143 the readline "ignore markers" (ASCII 0x01 and 0x02) are not
144 coloured. This option implies --ansi-colour-aware. <colour
145 spec> has the form <attr>;<fg>[;<bg>] Example: -p'1;31' will
146 give a bold red prompt on the current background (this is the
147 default when no argument is given). Google for 'ANSI color' to
148 learn more about colour codes. The argument is optional; if
149 given, it has to directly follow the option without an inter‐
150 vening space.
151 -P, --pre-given text
153 Start rlwrap with text in its edit buffer (this will automati‐
154 cally set the --always-readline option).
155 -q, --quote-characters <list_of_characters>
157 Assume that the given characters act as quotes, e.g. when match‐
158 ing parentheses. Take care to escape the list properly for your
159 shell (example: -q "\"'", which happens to be the default, or -q
160 "\"" which will be better for Lisp users)
161 -r, --remember
163 Put all words seen on in- and output on the completion list.
164 -R, --renice
166 Make rlwrap nicer than command (cf nice (1)). This may prevent
167 rlwrap from interrupting command to display a prompt when com‐
168 mand is still "thinking" about what to output next.
169 -s, --histsize <N>
171 Limit the history list to N entries, truncating the history file
172 (default: 300). A negative size -N means the same as N, but
173 treats the history file as read-only.
174 -S, --substitute-prompt <prompt>
176 Substitute the specified prompt for command's own prompt.
177 Mainly useful when command doesn't have a prompt.
178 -t, --set-term-name <name>
180 Set command's TERM to <name>. Programs that confuse rlwrap with
181 fancy screen control codes can sometimes be tamed by specifying
182 -t dumb
183 -v, --version
185 Print rlwrap version.
186 -w, --wait-before-prompt <timeout>
188 In order to determine if command's last output is a prompt,
189 rlwrap waits timeout millisecs after receiving it. Only when no
190 more output has arrived, it is cooked (coloured, filtered and/or
191 replaced by a substitute prompt) and displayed as a prompt.
192 Before this the prompt is displayed "uncooked". Most users won't
193 notice, but heavy cookers can prepend the timeout with a minus
194 sign, making rlwrap hold back the prompt until it has been
195 cooked ("patient mode"). This will prevent flashing of the
196 prompt, but it will also interfere with long output lines and
197 make switches from direct to readline mode less reliable.
198 Default timeout: 40 ms
199 -z, --filter <filter>
201 Use a filter to change rlwrap's behaviour. A filter can be used
202 to keep certain input out of the history, to change the prompt,
203 to implement simple macros or programmable completion.. rlwrap
204 comes with a special perl module (cf. RlwrapFilter(3pm)) for
205 easy filter writing. A number of example filters are installed
206 in the directory /usr/share/rlwrap/filters. "rlwrap -z <filter>"
207 displays information about a filter, "rlwrap -z listing" lists
208 all currently installed filters. If <filter> needs arguments,
209 you should quote the whole filter command line:
210 rlwrap -z 'filter args' command
212 If this command line contains shell metacharacters, rlwrap
214 passes it to the system shell for parsing.
215
217 Run nc (netcat) with command-line editing and history
218 rlwrap nc
219 Wrap smbclient (which uses readline itself), keep passwords out of the
221 history and don't wrap commands launched from smbclient (like more)
222 rlwrap -aPassword: -N smbclient //PEANUT/C
223 Wrap gauche (a Scheme interpreter) with a bold blue prompt, enable
225 mult-line editing and don't consider single quotes as quotes (so that
226 the parentheses in (print 'q) match)
227 rlwrap -pBlue -m -q'"' gosh
228 Get a list of all currently installed filters
230 rlwrap -z listing
231 Get help for the filter pipeto
233 rlwrap -z pipeto
234 Wrap sqlite3, use the pipeto filter to be able to pipe the output of
236 SQL commands through grep and/or less, complete (case-insensitively) on
237 the SQL keywords in 'sql_words'
238 rlwrap -a -z pipeto -i -f sql_words sqlite3 contacts.db
239 In a shell script, use rlwrap in 'one-shot' mode as a replacement for
241 read
242 order=`rlwrap -S 'Your pizza? '-H past_orders -P Margherita -o cat`
243
246 Most simple console commands put your terminal either in "cooked" or in
247 "raw" mode. In cooked mode the terminal will wait until you press the
248 ENTER key before handing the entire line to the program, in raw mode
249 every key you press is handed down immediately. In cooked mode you gen‐
250 erally can use the backspace key, but not the arrow keys, to edit your
251 input. Most simple console commands use cooked mode whenever they want
252 whole input lines, and raw mode when they want single keypresses. More
253 sophisticated commands tend to use raw mode all the time; they may
254 sometimes be rlwrappable with the -a (and -N) options.
255 When you rlwrap command, rlwrap will run it a in a separate session,
257 with its own "pseudo-terminal" (pty), and monitor this pty to see
258 whether the pty is in raw mode or in cooked mode. In the first case,
259 rlwrap will copy all input and output directly between command and your
260 terminal ("direct mode"). In the second case, rlwrap will use readline
261 to edit your input ("readline mode"), and monitor command's output -
262 every last line that doesn't end with a newline is a potential prompt.
263 How it handles such a candidate prompt depends on its being in
264 "patient" or "impatient" mode:
265
267 If command writes a lot of output, it tends to be written (and read) in
268 "chunks". Not all chunks will end with a newline, and we need to dis‐
269 tinguish their last lines from real prompts, especially if we want to
270 re-write ("cook") prompts. rlwrap solves this (almost) by waiting a
271 little, to see if there is more to come. "A little" is 40 msec by
272 default, but this can be changed with the -w option. Normally rlwrap
273 writes the suspected prompt as soon as it is received, replacing it
274 with a "cooked" version afer the wait time. This is called "impatient"
275 mode. If you don't like the flashing effect (which will only occur when
276 you "cook" the prompt heavily) you can put rlwrap in "patient mode" by
277 specifying a negative value with -w (e.g. -w -40). Rlwrap will then
278 hold back the prompt and only print if after cooking.
279
281 If and when rlwrap decides that it has a prompt, it will perform a num‐
282 ber of actions on it, depending on the given options: filtering (-z),
283 substituting (-S) and colouring (-p), in this order. The resulting
284 "cooked" prompt is then printed (after erasing the "raw" prompt, if
285 necessary)
286
288 Control + O
289 Accept the current line, but don't put it in the history list.
290 This action has a readline command name
291 rlwrap-accept-line-and-forget
292 Control + ^
294 Use an external editor to edit the current input (this will only
295 work if the -m option is set). This action has a readline com‐
296 mand name rlwrap-call-editor
297 These special keys were chosen because are not currently bound to any
299 readline action. If you don't like them, (or your window manager swal‐
300 lows them) they can be re-bound more sensibly by including lines like
301 the following in your ~/.inputrc:
302 "\M-\C-m": rlwrap-accept-line-and-forget # ESC-ENTER
304 "\C-xe": rlwrap-call-editor # CTRL-x e
305 cf. the readline(3) manpage for more about re-binding keys
307
309 RLWRAP_HOME:
310 directory in which the history and completion files are kept.
311 RLWRAP_EDITOR (or else EDITOR, or else VISUAL):
313 editor to use for multi-line input. Example:
314 export RLWRAP_EDITOR="microemacs -l%L:%C"
316 export RLWRAP_EDITOR="vi +%L"
317 The last example is the default; %L and %C are replaced by line and
319 column numbers corresponding to the cursor position in rlwrap's edit
320 buffer
321 RLWRAP_FILTERDIR:
323 Any executable along your PATH can in theory be used as a fil‐
324 ter, but because filters have to follow a rather outlandish pro‐
325 tocol (cf. RlwrapFilter (3)) it is a good idea to keep them sep‐
326 arate. This is why rlwrap adds a special filter directory to
327 $PATH just before launching a filter. By default, this is
328 /usr/share/rlwrap/filters, but $RLWRAP_FILTERDIR is used if set.
329
331 A number of signals are forwarded to command: HUP INT QUIT USR1 USR2
332 TERM and (by way of resizing command's terminal) WINCH. Some care is
333 taken to handle TSTP (usually a result of a CTRL-Z from the terminal)
334 sensibly - for example, after suspending rlwrap in the middle of a line
335 edit, continuing (by typing 'fg') will land you at the exact spot where
336 you suspended it.
337 Filters that take more than 1 second to respond can be interrupted by a
339 CTRL-C from the terminal (although rlwrap will not survive this)
340 If command changes the keystrokes that send a particular signal from
342 the keyboard (like emacs, which uses CTRL-G instead of CTRL-C) rlwrap
343 will do the same.
344 When command is killed by a signal, rlwrap will clean up, reset its
346 signal handlers an then commit suicide by sending the same signal to
347 itself. This means that your shell sees the same exit status as it
348 would have seen without rlwrap.
349
352 When the standard input is not a terminal, editing input doesn't make
353 sense, so rlwrap will ignore all options and simply execute command.
354 When stdout (or stderr) is not a terminal, rlwrap will re-open it to
355 /dev/tty (the users terminal) after it has started command, so that
356 command's output is redirected as expected, but keyboard input and
357 rlwrap error messages are still visible.
358 The upshot of this is that rlwrap command behaves more or less like
360 command when redirecting.
361
364 non-zero after a rlwrap error, or else command's exit status. rlwrap
365 will always leave the terminal in a tidy state, even after a crash.
366
368 rlwrap expects its history and completion files in $RLWRAP_HOME, but
369 uses .dotfiles in the user's home directory if this variable is not
370 set. This will quickly become messy if you use rlwrap a lot.
371 $RLWRAP_HOME/command_history, ~/.command_history
373 History for command
374 $RLWRAP_HOME/command_completions, ~/.command_completions
376 Per-user completion word list for command. rlwrap never writes
377 into this list, but one can combine -l and -f options to to sim‐
378 ulate the effect of a -r option that works across invocations.
379 /usr/share/rlwrap/completions/command
381 System-wide completion word list for command. This file is only
382 consulted if the per-user completion word list is not found.
383 $INPUTRC, ~/.inputrc
385 Individual readline initialisation file (See readline [22m(3) for
386 its format). rlwrap sets its application name to command (unless
387 you use the -C option), enabling different behaviours for dif‐
388 ferent commands. One could e.g. put the following lines in
389 ~/.inputrc:
390 $if coqtop
392 set show-all-if-ambiguous On
393 $endif
394 making rlwrap show all completions whenever it runs coqtop
396
398 Though it is flexible, delivers the goods (readline functionality), and
399 adheres to the Unix "many small tools" paradigm, rlwrap is a kludge.
400 It cannot know anything about command's internal state, which makes
401 context-sensitive completion impossible. Using the readline library
402 from within command is still the best option.
403 Also, because "it takes two to tango" there is no way for rlwrap to
405 synchronise its internal state with command, resulting in a number of
406 subtle race conditions, where e.g. command may have changed the state
407 of its terminal before rlwrap has read command output that was written
408 before the state change. You will notice these races especially on a
409 busy machine and with heavy "cooking" and filtering, when suddenly (and
410 unpredictably) promtps or command output are garbled or incorrectly
411 coloured.
412 Filtering is a very recent addition, and should be considered alpha
414 quality.
415 rlwrap can try, but often fails to, handle prompts that contain control
417 characters. A flter may be used to clean up the prompt.
418
421 This manpage documents rlwrap version 0.37
422
424 The readline library (written by Chet Ramey) does all the hard work
425 behind the scenes, the pty-handling code has been taken practically
426 unchanged from rxvt-2.7.10 (currently maintained by Geoff C. Wing), and
427 completion word lists are managed by Damian Ivereigh's libredblack
428 library. The few remaining lines of code were written by Hans Lub
429 (hanslub42@gmail.com).
430
432 readline(3), RlwrapFilter(3pm)
433 January 4, 2010 rlwrap(1)