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 (and almost suceeds) to be completely transparent - you
16 (or your shell) shouldn't notice any difference between command and
17 rlwrap command - except the added readline functionality, of course.
18 This should even hold true when you are re-directing, piping and send‐
19 ing signals from and to command, and when command manipulates its ter‐
20 minal settings or working directory.
21 There are many options to add (programmable) completion, handle
23 multi-line input, colour and re-write prompts. If you don't need them
24 (and you probably don't), you can skip the rest of this manpage.
25
27 -a, --always-readline [password_prompt]
28 Always remain in "readline mode", regardless of command's termi‐
29 nal settings. Use this option if you want to use rlwrap with
30 commands that already do some line editing. NB: With this
31 option, rlwrap will echo (and save) passwords, unless you give
32 command's password prompt as an argument. The argument is
33 optional; if given, it has to directly follow the option with‐
34 out an intervening space.
35 On a linux machine you can use the -N (--no-children) option to
37 avoid wrapping pagers and editors called from command; this
38 should make them much more usable
39 Many commands that need --always-readline may also need -t dumb
41 to prevent terminal control sequences from confusing rlwrap
42 (although this will annoy the above-mentioned pagers and edi‐
43 tors)
44 -A, --ansi-colour-aware
47 Prompts that use colour will confuse rlwrap, especially at the
48 end of long input lines. This option will make rlwrap better
49 behaved in such cases. If the prompt contains anything fancier
50 than ANSI colour codes, this option may actually make things
51 worse.
52 -b, --break-chars list_of_characters
54 Consider the specified characters word-breaking (whitespace is
55 always word-breaking). This determines what is considered a
56 "word", both when completing and when building a completion word
57 list from files specified by -f options following (not preced‐
58 ing!) it. Default list (){}[],'+-=&^%$#@"";|\ Unless -c is
59 specified, / and . (period) are included in the default list.
60 -c, --complete-filenames
62 Complete filenames (filename completion is always case-sensi‐
63 tive, even with the -i option). On Linux, OS X, FreeBSD and
64 Solaris rlwrap will keep track of command's working directory,
65 so that relative filenames will be completed as one would
66 expect.
67 -C, --command-name command_name|N
69 Use command_name instead of command to determine the names of
70 history and completion files, and to initialise readline (as
71 specified in ~/.inputrc). A numeric argument N > 0 means: use
72 the Nth argument counting backwards from the end of the argument
73 list
74 -D, --history-no-dupes n
76 How aggressively to weed out duplicate entries from the input
77 history. If n = 0, all inputs are kept in the history list, if
78 n = 1 (this is the default) consecutive duplicates are dropped
79 from the list, while n = 2 will make rlwrap drop all previous
80 occurrences of the current input from the list.
81 -e, --extra-char-after-completion char
83 By default, rlwrap appends a space after any inserted completion
84 text. Use this option to change this to '' (don't insert any‐
85 thing) or some other character.
86 -f, --file file
88 Split file into words (using the default word-breaking charac‐
89 ters, or those specified by --break-chars), and add them to the
90 completion word list. This option can be given more than once,
91 and adds to the default completion list in $RLWRAP_HOME or
92 /usr/share/rlwrap/completions.
93 Specifying -f . will make rlwrap use the current history file as
95 a completion word list.
96 -g, --forget-matching regexp
98 Forget (i.e. never put into the history list) all input lines
99 that match the POSIX 1003.2 regular expression regexp. The
100 match is always case-insensitive. regexp may be an ordinary
101 string. For more about regular expressions, see regex (7)
102 -h, --help
104 Print a short help message.
105 -H, --history-filename file
107 Read command history from file (and write it back there if
108 --histsize >= 0)
109 -i, --case-insensitive
111 Ignore case when completing (filename completion remains
112 case-sensitive). This option has to come before any -f options.
113 -I, --pass-sigint-as-sigterm
115 Send a TERM signal to command when an INT is received (e.g. when
116 you press CTRL-C).
117 -l, --logfile file
119 When in readline mode, append command's output (including
120 echo'ed user input) to file (creating file when it doesn't
121 exist).
122 -n, --no-warnings
124 Don't print warnings.
125 -N, --no-children
127 Don't rlwrap command's children: whenever rlwrap notices that
128 command is waiting for one of its children, it switches to
129 direct mode, handing down all keypresses immediately. With this
130 option commands that need --always-readline can call editors and
131 pagers and still be usable.
132 This option needs /proc/command_pid/wchan, so it only works with
134 linux kernels configured with CONFIG_KALLSYMS.
135 -m, --multi-line [newline_substitute]
137 Enable multi-line input using a "newline substitute" character
138 sequence (" \ ", [space-backslash-space] by default). Newline
139 substitutes are translated to newlines before sending the input
140 to command. With this option, you can call an external editor
141 $RLWRAP_EDITOR on the (expanded) current input with the
142 rlwrap_call_editor key (CTRL-^ by default) The argument is
143 optional; if given, it has to directly follow the option with‐
144 out an intervening space.
145 -M, --multi-line-ext .ext
147 Call multi-line-editor on temporary files with filename exten‐
148 sion .ext (useful for e.g. automatic syntax colouring)
149 -o, --one-shot
151 Send an EOF to command after accepting the first line of input
152 -O, --only-cook regexp
154 Only ever "cook" prompts that match regexp
155 -p, --prompt-colour [colour_name|Colour_name|colour_spec]
157 Use one of the colour names black, red, green, yellow, blue,
158 cyan, purple (=magenta) or white, or an ANSI-conformant
159 <colour_spec> to colour any prompt displayed by command. An
160 uppercase colour name (Yellow or YELLOW ) gives a bold prompt.
161 Prompts that already contain (colour) escape sequences or one of
162 the readline "ignore markers" (ASCII 0x01 and 0x02) are not
163 coloured. This option implies --ansi-colour-aware. colour spec
164 has the form <attr>;<fg>[;<bg>] Example: -p'1;31' will give a
165 bold red prompt on the current background (this is the default
166 when no argument is given). Google for 'ANSI color' to learn
167 more about colour codes. The argument is optional; if given, it
168 has to directly follow the option without an intervening space.
169 -P, --pre-given text
171 Start rlwrap with text in its edit buffer (this will automati‐
172 cally set the --always-readline option).
173 -q, --quote-characters list_of_characters
175 Assume that the given characters act as quotes, e.g. when match‐
176 ing parentheses. Take care to escape the list properly for your
177 shell (example: -q "\"'", which happens to be the default, or -q
178 "\"" which will be better for lisp-like input)
179 -r, --remember
181 Put all words seen on in- and output on the completion list.
182 -R, --renice
184 Make rlwrap nicer than command (cf nice (1)). This may prevent
185 rlwrap from interrupting command to display a prompt when com‐
186 mand is still "thinking" about what to output next.
187 -s, --histsize N
189 Limit the history list to N entries, truncating the history file
190 (default: 300). A negative size -N (even -0) means the same as
191 N, but treats the history file as read-only.
192 -S, --substitute-prompt prompt
194 Substitute the specified prompt for command's own prompt.
195 Mainly useful when command doesn't have a prompt.
196 -t, --set-term-name name
198 Set command's TERM to name. Programs that confuse rlwrap with
199 fancy screen control codes can sometimes be tamed by specifying
200 -t dumb
201 -U, --mirror-arguments
203 (linux only) Keep track of command's arguments as seen by the ps
204 [1m(1) command, and mirror them in rlwrap's own arguments This is
205 mainly useful for commands that overwrite command-line password
206 arguments that would be exposed by rlwrap without this option.
207 -v, --version
209 Print rlwrap version.
210 -w, --wait-before-prompt timeout
212 In order to determine if command's last output is a prompt,
213 rlwrap waits timeout milliseconds after receiving it. Only when
214 no more output has arrived, it is cooked (coloured, filtered
215 and/or replaced by a substitute prompt) and displayed as a
216 prompt. Before this the prompt is displayed "uncooked". Most
217 users won't notice, but heavy cookers can prepend the timeout
218 with a minus sign, making rlwrap hold back the prompt until it
219 has been cooked ("patient mode"). This will prevent flashing of
220 the prompt, but it will also interfere with long output lines
221 and make switches from direct to readline mode less reliable.
222 Default timeout: 40 ms
223 -W, --polling
225 EXPERIMENTAL: Wake up every timeout millisecs, where timeout is
226 the same as for the -w (--wait-before-prompt) option, 40 ms by
227 default. This is used to sense the slave's interrupt character
228 and ISIG flag and to adjust stdin's terminal settings accord‐
229 ingly, even before you press a key. Try this option e.g. when
230 CTRL-C acts differently on command with, and without, rlwrap.
231 -z, --filter filter
233 Use a filter to change rlwrap's behaviour. A filter can be used
234 to keep certain input out of the history, to change the prompt,
235 to implement simple macros or programmable completion.. rlwrap
236 comes with a perl and a Python 3 module to make filter writing
237 easy. (cf. RlwrapFilter(3pm) for the perl module, the python one
238 is very similar) A number of example filters are installed in
239 the directory /usr/share/rlwrap/filters. "rlwrap -z filter"
240 displays information about a filter, "rlwrap -z listing" lists
241 all currently installed filters. If filter needs arguments, you
242 should quote the whole filter command line:
243 rlwrap -z 'filter args' command ...
245 rlwrap -z 'pipeline filter1 ... : filter2 ... : ...' command ...
246 If this command line contains shell metacharacters, rlwrap
248 passes it to the system shell for parsing.
249
251 Run nc (netcat) with command-line editing and history
252 rlwrap nc
253 Wrap smbclient (which uses readline itself), keep passwords out of the
255 history and don't wrap commands launched from smbclient (like more)
256 rlwrap -aPassword: -N smbclient //PEANUT/C
257 Wrap gauche (a Scheme interpreter) with a bold blue prompt, enable
259 multi-line editing (using .scm as filename extension) and don't con‐
260 sider single quotes as quotes (so that the parentheses in e.g. (print
261 'q) match)
262 rlwrap -pBlue -m -M .scm -q'
263 Get a list of all currently installed filters
265 rlwrap -z listing
266 Get help for the filter pipeto
268 rlwrap -z pipeto
269 Wrap sqlite3, use the pipeto filter to be able to pipe the output of
271 SQL commands through grep and/or less, complete (case-insensitively) on
272 the SQL keywords in 'sql_words'
273 rlwrap -a -z pipeto -i -f sql_words sqlite3 contacts.db
274 In a shell script, use rlwrap in 'one-shot' mode as a replacement for
276 read
277 order=$(rlwrap -pYellow -S 'Your pizza? ' -H
278 past_orders -P Margherita -o cat)
279
282 Most simple console commands put your terminal either in "cooked" or in
283 "raw" mode. In cooked mode the terminal will wait until you press the
284 ENTER key before handing the entire line to the program, in raw mode
285 every key you press is handed down immediately. In cooked mode you gen‐
286 erally can use the backspace key, but not the arrow keys, to edit your
287 input. Most simple console commands use cooked mode whenever they want
288 whole input lines, and raw mode when they want single keypresses. More
289 sophisticated commands tend to use raw mode all the time; they may
290 sometimes be rlwrappable with the -a (and -N) options.
291 When you rlwrap command, rlwrap will run it a in a separate session,
293 under its own (controlling) "pseudo-terminal" (pty), and monitor this
294 pty to see whether it is in raw, or in cooked mode. In the first case,
295 rlwrap will copy all input and output directly between command and your
296 terminal ("direct mode"). In the second case, rlwrap will use readline
297 to edit your input ("readline mode"), and monitor command's output -
298 every last line that doesn't end with a newline is a potential prompt.
299 How it handles such a candidate prompt depends on its being in
300 "patient" or "impatient" mode:
301
303 If command writes a lot of output, it tends to be written (and read) in
304 "chunks". Not all chunks will end with a newline, and we need to dis‐
305 tinguish their last lines from real prompts, especially if we want to
306 re-write ("cook") prompts. rlwrap solves this (almost) by waiting a
307 little, to see if there is more to come. "A little" is 40 msec by
308 default, but this can be changed with the -w option. Normally rlwrap
309 writes the suspected prompt as soon as it is received, replacing it
310 with a "cooked" version after the wait time. This is called "impatient"
311 mode. If you don't like the flashing effect (which can become annoying
312 when you "cook" the prompt heavily) you can put rlwrap in "patient
313 mode" by specifying a negative value with -w (e.g. -w -40). Rlwrap
314 will then hold back the prompt and only print if after cooking.
315
317 If and when rlwrap decides that it has a prompt, it will perform a num‐
318 ber of actions on it, depending on the given options: filtering (-z),
319 substituting (-S) and colouring (-p), in this order. The resulting
320 "cooked" prompt is then printed (after erasing the "raw" prompt, if
321 necessary)
322
324 Control + O
325 Accept the current line, but don't put it in the history list.
326 This action has a readline command name
327 rlwrap-accept-line-and-forget
328 Control + ^
330 Use an external editor (see RLWRAP_EDITOR below) to edit the
331 current input (this will only work if the -m option is set).
332 This action has a readline command name rlwrap-call-editor
333 (Not currently bound)
335 Any key can be bound to the readline command rlwrap-direct-key‐
336 press. This key will then always be sent directly to command,
337 even when rlwrap is not in direct mode.
338 (Not currently bound)
340 Any key can be bound to the readline command rlwrap-hotkey. This
341 key will then cause the current input line and the current his‐
342 tory to be filtered (cf. RlwrapFilter(3pm)) through the current
343 filter (hence be a no-op when there is no filter), which then
344 can re-write the input line, move the cursor and update the his‐
345 tory. After that, the user can still edit the resulting input.
346 (Not currently bound)
348 rlwrap-hotkey-without-history acts like rlwrap-hotkey, but the
349 history (which can be quite large) is not passed to the filter.
350 This is more efficient if the filter wouldn't do anything useful
351 with the history anyway.
352 The special keys were chosen for no other reason than that they are
354 not currently bound to any readline action. If you don't like them, (or
355 your window manager swallows them) they (and the other 3 commands) can
356 be re-bound more sensibly by including lines like the following in your
357 ~/.inputrc:
358 "\M-\C-m": rlwrap-accept-line-and-forget # ESC-ENTER to accept but keep out of history
360 "\C-xe": rlwrap-call-editor # CTRL-x e to edit (multi-line) input in editor of your choice
361 $if erl # (only) for the Erlang shell:
362 "\C-g": rlwrap-direct-keypress # pass CTRL-g directly to enter 'user switch' command
363 $endif
364 "\C-y": rlwrap-hotkey-without-history # CTRL-y to filter input line (and e.g. insert X selection)
365 cf. the readline(3) manpage. (NB: take care to not use keys that are
367 already caught by the terminal driver, like CTRL+S, as rlwrap will
368 never see those)
369
371 RLWRAP_HOME:
372 directory in which the history and completion files are kept.
373 RLWRAP_EDITOR (or else EDITOR, or else VISUAL):
375 editor to use for multi-line input (and rlwrap-edit-history).
376 Example:
377 export RLWRAP_EDITOR="vi +%L"
379 export RLWRAP_EDITOR="vim '+call cursor(%L,%C)'"
380 export RLWRAP_EDITOR="emacs +%L:%C %F"
381 The first example above is the default; %L and %C are replaced by line
383 and column numbers corresponding to the cursor position in rlwrap's
384 edit buffer, %F is replaced by name of the (temporary) file. If %F is
385 not used, this name is put after the (expanded) $RLWAP_EDITOR
386 RLWRAP_FILTERDIR:
388 Any executable along your PATH can in theory be used as a fil‐
389 ter, but because filters have to follow a rather outlandish pro‐
390 tocol (cf. RlwrapFilter (3)) it is a good idea to keep them sep‐
391 arate. This is why rlwrap adds a special filter directory in
392 front of $PATH just before launching a filter. By default, this
393 is /usr/share/rlwrap/filters, but $RLWRAP_FILTERDIR is used if
394 set.
395
397 A number of signals are forwarded to command: HUP INT QUIT USR1 USR2
398 TERM and (by way of resizing command's terminal) WINCH. Some care is
399 taken to handle TSTP (usually a result of a CTRL-Z from the terminal)
400 sensibly - for example, after suspending rlwrap in the middle of a line
401 edit, continuing (by typing 'fg') will land you at the exact spot where
402 you suspended it.
403 Filters that take more than 1 second to respond can be interrupted by a
405 CTRL-C from the terminal (although rlwrap will not survive this)
406 If command changes the keystrokes that send a particular signal from
408 the keyboard (like emacs, which uses CTRL-G instead of CTRL-C) rlwrap
409 will do the same (but only after the next keystroke - use the --polling
410 option to make rlwrap more transparent in this respect)
411 When command is killed by a signal, rlwrap will clean up, reset its
413 signal handlers an then commit suicide by sending the same signal to
414 itself. This means that your shell sees the same exit status as it
415 would have seen without rlwrap.
416
419 When the standard input is not a terminal, editing input doesn't make
420 sense, so rlwrap will ignore all options and simply execute command.
421 When stdout (or stderr) is not a terminal, rlwrap will re-open it to
422 /dev/tty (the users terminal) after it has started command, so that
423 command's output is redirected as expected, but keyboard input and
424 rlwrap error messages are still visible.
425 The upshot of this is that rlwrap command behaves more or less like
427 command when redirecting.
428
431 non-zero after a rlwrap error, or else command's exit status. rlwrap
432 will always leave the terminal in a tidy state, even after a crash.
433
435 rlwrap expects its history and completion files in $RLWRAP_HOME, but
436 uses .dotfiles in the user's home directory if this variable is not
437 set. This will quickly become messy if you use rlwrap for many differ‐
438 ent commands.
439 $RLWRAP_HOME/command_history, ~/.command_history
441 History for command (remember that command may be overriden by
442 the --command-name (or -C) option)
443 $RLWRAP_HOME/command_completions, ~/.command_completions
445 Per-user completion word list for command. rlwrap never writes
446 into this list, but one can combine -l and -f options to to sim‐
447 ulate the effect of a -r option that works across invocations.
448 /usr/share/rlwrap/completions/command
450 System-wide completion word list for command. This file is only
451 consulted if the per-user completion word list is not found.
452 $INPUTRC, ~/.inputrc
454 Individual readline initialisation file (See readline [22m(3) for
455 its format). rlwrap sets its application name to command (this
456 can be overridden by the -C option), enabling different behav‐
457 iours for different commands. One could e.g. put the following
458 lines in ~/.inputrc:
459 $if coqtop
461 set show-all-if-ambiguous On
462 $endif
463 making rlwrap show all completions whenever it runs coqtop
465
467 Though it is flexible, delivers the goods (readline functionality), and
468 adheres to the Unix "many small tools" paradigm, rlwrap is a kludge.
469 It cannot know anything about command's internal state, which makes
470 context-sensitive completion impossible. Using the readline library
471 from within command is still the best option.
472 Also, because "it takes two to tango" there is no way for rlwrap to
474 synchronise its internal state with command, resulting in a number of
475 subtle race conditions, where e.g. command may have changed the state
476 of its terminal before rlwrap has read command output that was written
477 before the state change. You will notice these races especially on a
478 busy machine and with heavy "cooking" and filtering, when suddenly (and
479 unpredictably) promtps or command output are garbled or incorrectly
480 coloured.
481 rlwrap can try, but often fails to, handle prompts that contain control
483 characters. A filter may be used to clean up the prompt.
484
487 This manpage documents rlwrap version 0.43
488
490 The readline library (written by Brian Fox and Chet Ramey) does all the
491 hard work behind the scenes, the pty-handling code has been taken prac‐
492 tically unchanged from rxvt-2.7.10 (currently maintained by Geoff C.
493 Wing), and completion word lists are managed by Damian Ivereigh's
494 libredblack library. The few remaining lines of code were written by
495 Hans Lub (hanslub42@gmail.com).
496
498 readline(3), RlwrapFilter(3pm)
499 July 19, 2016 rlwrap(1)