1rlwrap(1) General Commands Manual rlwrap(1)
2
6 rlwrap - readline wrapper
7
13 rlwrap [rlwrap-options] command ...
14
16 rlwrap runs the specified command, intercepting user input in order to
17 provide readline's line editing, persistent history and completion.
18 rlwrap tries (and almost succeeds) to be completely transparent - you
20 (or your shell) shouldn't notice any difference between command and rl‐
21 wrap command - except the added readline functionality, of course.
22 This should even hold true when you are re-directing, piping and send‐
23 ing signals from and to command, and when command manipulates its ter‐
24 minal settings, working directory or (with the -U option) command line.
25 There are many options to add (programmable) completion, handle
27 multi-line input, colour and re-write prompts. If you don't need them
28 (and you probably don't), you can skip the rest of this manpage, al‐
29 though some of those options could make your command line quite a bit
30 more comfortable...
31
33 -a[password_prompt], --always-readline[=password_prompt]
34 Always remain in "readline mode" (see below), regardless of com‐
35 mand's terminal settings. If rlwrap "does nothing" this is the
36 option to use, as command is apparently already doing its own
37 line editing. NB: With this option, rlwrap will echo (and save)
38 passwords, unless you give command's password prompt as an argu‐
39 ment.
40 The argument is optional; if given, it has to directly follow a
42 short option without an intervening space (-aPassword:) and a
43 long option with an equals sign (--always-readline=Password:).
44 The -N (--no-children) option can be used to avoid wrapping
46 pagers and editors called from command; this should make them
47 much more usable
48 -A[!], --ansi-colour-aware[=!]
51 Prompts that use colour, or use other CSI codes to e.g. set win‐
52 dow titles or enable bracketed-paste will confuse rlwrap, espe‐
53 cially at the end of long input lines. This option will usually
54 (but by no means always) make rlwrap better behaved in such
55 cases.
56 Giving '!' as an argument will make rlwrap remove all color
58 codes from the prompt.
59 The argument is optional; if given, it has to directly follow a
61 short option without an intervening space (-A!) and a long op‐
62 tion with an equals sign (--ansi-colour-aware=!).
63 -b, --break-chars list_of_characters
66 Consider the specified characters word-breaking (whitespace is
67 always word-breaking). This determines what is considered a
68 "word", both when completing and when building a completion word
69 list from files specified by -f options following (not preced‐
70 ing!) it. Default list (){}[],'+-=&^%$#@";|\ Unless -c is spec‐
71 ified, / and . (period) are included in the default list.
72 -c, --complete-filenames
75 Complete filenames (filename completion is always case-sensi‐
76 tive, even with the -i option). On Linux, OS X, FreeBSD and So‐
77 laris rlwrap will keep track of command's working directory, so
78 that relative filenames will be completed as one would expect.
79 -C, --command-name command_name|N
82 Use command_name instead of command to determine the names of
83 history and completion files, and to initialise readline (as
84 specified in ~/.inputrc). A numeric argument N > 0 means: use
85 the Nth argument counting backwards from the end of the argument
86 list
87 -D, --history-no-dupes n
90 How aggressively to weed out duplicate entries from the input
91 history. If n = 0, all inputs are kept in the history list, if
92 n = 1 (this is the default) consecutive duplicates are dropped
93 from the list, while n = 2 will make rlwrap drop all previous
94 occurrences of the current input from the list.
95 -e, --extra-char-after-completion char
98 By default, rlwrap appends a space after any inserted completion
99 text. Use this option to change this to '' (don't insert any‐
100 thing) or some other character.
101 -E, --always-echo
104 By default, rlwrap avoids displaying passwords by echoing '***'
105 whenever the client clears the ECHO flag on its input. This op‐
106 tion will make rlwrap ignore this ECHO flag and always echo the
107 user's input. (-aPassword: will still work as expected)
108 -f, --file file
112 Split file into words (using the default word-breaking charac‐
113 ters, or those specified by --break-chars), and add them to the
114 completion word list. This option can be given more than once,
115 and adds to the default completion list in $RLWRAP_HOME or
116 /usr/share/rlwrap/completions.
117 Specifying -f . will make rlwrap use the current history file as
119 a completion word list.
120 -g, --forget-matching regexp
123 Forget (i.e. never put into the history list) input lines that
124 match the POSIX 1003.2 regular expression regexp. The match is
125 always case-insensitive. perl-style character classes like '\d'
126 are not recognised, use '[:digit:]'. For more about regular ex‐
127 pressions, see regex (7)
128 -h, --help
131 Print a short help message.
132 -H, --history-filename file
135 Read command history from file (and write it back there if
136 --histsize >= 0)
137 -i, --case-insensitive
140 Ignore case when completing (filename completion remains
141 case-sensitive). This option has to come before any -f options.
142 -I, --pass-sigint-as-sigterm
145 Send a TERM signal to command when an INT is received (e.g. when
146 you press CTRL-C).
147 -l, --logfile file
150 When in readline mode, append command's output (including
151 echo'ed user input) to file (creating file when it doesn't ex‐
152 ist).
153 -m[newline_substitute], --multi-line[=newline_substitute]
156 Enable multi-line input using a "newline substitute" character
157 sequence (" \ ", [space-backslash-space] by default). Newline
158 substitutes are translated to newlines before sending the input
159 to command. With this option, you can call an external editor
160 $RLWRAP_EDITOR on the (expanded) current input with the rl‐
161 wrap_call_editor key (CTRL-^ by default) The argument is op‐
162 tional; if given, it has to directly follow a short option with‐
163 out an intervening space (-m';;') and a long option with an
164 equals sign (--multi-line=';;').
165 -M, --multi-line-ext .ext
168 Call multi-line-editor on temporary files with filename exten‐
169 sion .ext (useful for e.g. automatic syntax colouring)
170 -n, --no-warnings
174 Don't print warnings.
175 -N, --no-children
178 When rlwrap is invoked with the --always-readline option, edi‐
179 tors and pagers that are called by the client will be pretty un‐
180 usable, as they will see your keypresses only if you press EN‐
181 TER. rlwrap -N will avoid this problem by switching to direct
182 mode if it thinks command is waiting for one of its children.
183 -o, --one-shot
186 Send an EOF to command after accepting the first line of input
187 -O, --only-cook regexp
189 Only ever "cook" prompts that match regexp, which can be pre‐
190 ceded by '!', meaning that all matching candidate prompts will
191 be cooked immediately ("confident mode").
192 -p[colour], --prompt-colour[=colour]
195 Use one of the colour names black, red, green, yellow, blue,
196 cyan, purple (=magenta) or white, or an ANSI-conformant
197 <colour_spec> to colour any prompt displayed by command. An up‐
198 percase colour name (Yellow or YELLOW ) gives a bold prompt.
199 Prompts that already contain (colour) escape sequences or one of
200 the readline "ignore markers" (ASCII 0x01 and 0x02) are not
201 coloured. This option implies --ansi-colour-aware. You can also
202 use a colour spec of the form <attr>;<fg>[;<bg>], for example
203 -p'1;31' will give a bold red prompt on the current background
204 (this is the default when no argument is given). Google for
205 'ANSI color' to learn more about colour codes. The argument is
206 optional; if given, it has to directly follow a short option
207 without an intervening space (-p'Red') and a long option with an
208 equals sign (--prompt-colour='Red').
209 -P, --pre-given text
212 Start rlwrap with text in its edit buffer (this will automati‐
213 cally set the --always-readline option).
214 -q, --quote-characters list_of_characters
217 Assume that the given characters act as quotes, e.g. when match‐
218 ing parentheses. Take care to escape the list properly for your
219 shell (example: -q "\"'", which happens to be the default, or -q
220 "\"" which will be better for lisp-like input)
221 -r, --remember
224 Put all words seen on in- and output on the completion list.
225 -R, --renice
228 Make rlwrap nicer than command (cf nice (1)). This may prevent
229 rlwrap from interrupting command to display a prompt when com‐
230 mand is still "thinking" about what to output next.
231 -s, --histsize N
234 Limit the history list to N entries, truncating the history file
235 (default: 300). A negative size -N (even -0) means the same as
236 N, but treats the history file as read-only.
237 -S, --substitute-prompt prompt
240 Substitute the specified prompt for command's own prompt. Mainly
241 useful when command doesn't have a prompt.
242 -t, --set-term-name name
245 Set command's TERM to name. Programs that confuse rlwrap with
246 fancy screen control codes can sometimes be tamed by specifying
247 -t dumb
248 -U, --mirror-arguments
251 (linux only) Keep track of command's arguments as seen by the ps
252 [1m(1) command, and mirror them in rlwrap's own arguments This can
253 be useful for commands that overwrite command-line password ar‐
254 guments that would be exposed by rlwrap without this option. The
255 mirroring takes place after the first user input, or every few
256 milliseconds, if you use the --polling option.
257 -v, --version
260 Print rlwrap version.
261 -w, --wait-before-prompt timeout
264 In order to determine if command's last output is a prompt, rl‐
265 wrap waits timeout milliseconds after receiving it. Only when
266 no more output has arrived, it is cooked (coloured, filtered
267 and/or replaced by a substitute prompt) and displayed as a
268 prompt. Before this the prompt is displayed "uncooked". Most
269 users won't notice, but heavy cookers can prepend the timeout
270 with a minus sign, making rlwrap hold back the prompt until it
271 has been cooked ("patient mode"). This will prevent flashing of
272 the prompt, but it will also interfere with long output lines
273 and make switches from direct to readline mode less reliable.
274 Default timeout: 40 ms
275 -W, --polling
278 EXPERIMENTAL: Wake up every timeout millisecs, where timeout is
279 the same as for the -w (--wait-before-prompt) option, 40 ms by
280 default. This is used to sense the slave's interrupt character
281 and ISIG flag and to adjust stdin's terminal settings accord‐
282 ingly, even before you press a key. Try this option e.g. when
283 CTRL-C acts differently on command with, and without, rlwrap.
284 -z, --filter some_filter
287 Use some_filter to change rlwrap's behaviour. Filters can be
288 used to keep certain input out of the history, to change the
289 prompt, to implement simple macros, programmable hotkeys for
290 e.g. fuzzy history search, and programmable completion. rlwrap
291 comes with a perl and a python module to make filter writing
292 easy. (cf. RlwrapFilter(3pm) for the perl module, the python one
293 is very similar) A number of example filters are installed in
294 the directory /usr/share/rlwrap/filters.
295 rlwrap -z listing
297 lists all currently installed filters, while
299 rlwrap -z some_filter
301 displays information about some_filter
303 If some_filter needs arguments, you should quote the whole fil‐
306 ter command line:
307 rlwrap -z 'some_filter args' command ...
309 rlwrap -z 'pipeline filter1 ... : filter2 ... : ...' command ...
310 If this command line contains shell metacharacters, rlwrap
313 passes it to the system shell for parsing.
314 As filters have to follow a special protocol, shell commands
316 like sed and grep cannot be used as rwlrap filters. They can,
317 however, be converted into filters by the makefilter filter:
318 rlwrap -z 'makefilter egrep -i --color "error|$"' command
320 will color all occurrences of "error" (or "Error") in command's
322 output, while
323 rlwrap -z 'makefilter --message-type history sed -e
325 s"/whisky/lemonade/"' command
326 sanitises your drinking history. Both filters can be combined
328 using the pipeline filter, of course.
329
333 Run nc (netcat) with command-line editing and history
334 rlwrap nc
335 Wrap smbclient (which uses readline itself), keep passwords out of the
337 history and don't interfere with pagers (like less) called by smb‐
338 client.
339 rlwrap -aPassword: -N smbclient //PEANUT/C
340 Wrap sensitive_app, hide password from ps (if sensitive_app does so)
342 and keep all input that starts with a space out of history:
343 rlwrap -g '^ ' -U sensitive_app --password MySeCrEt
344 Wrap gauche (a Scheme interpreter) with a bold blue prompt, enable
346 multi-line editing (using .scm as filename extension) and don't con‐
347 sider single quotes as quotes (so that the parentheses in e.g. (print
348 'q) match)
349 rlwrap -pBlue -m -M .scm -q'"' gosh
350 Wrap sqlite3, use the pipeto filter to be able to pipe the output of
352 SQL commands through grep and/or less, complete (case-insensitively) on
353 the SQL keywords in 'sql_words'
354 rlwrap -a -z pipeto -i -f sql_words sqlite3 contacts.db
355 In a shell script, use rlwrap in 'one-shot' mode as a replacement for
357 read
358 order=$(rlwrap -pYellow -S 'Your pizza? ' -H past_or‐
359 ders -P Margherita -o cat)
360
363 Most simple console commands put your terminal either in "cooked" or in
364 "raw" mode. In cooked mode the terminal will wait until you press the
365 ENTER key before handing the entire line to the program, in raw mode
366 every key you press is handed down immediately. In cooked mode you gen‐
367 erally can use the backspace key, but not the arrow keys, to edit your
368 input.
369 When you rlwrap command, rlwrap will run it a in a separate session,
371 under its own (controlling) "pseudo-terminal" (pty), and monitor this
372 pty to see whether it is in raw, or in cooked mode. In the first case,
373 rlwrap will copy all input and output directly between command and your
374 terminal ("direct mode"). In the second case, rlwrap will use readline
375 to edit your input ("readline mode"), and monitor command's output -
376 every last line that doesn't end with a newline is a potential prompt.
377 How it handles such a candidate prompt depends on its being in "pa‐
378 tient" or "impatient" mode, see below.
379 Simple console commands use cooked mode whenever they want whole input
381 lines, and raw mode when they want single keypresses. Those are the
382 progams for which rlwrap is most useful. More sophisticated commands
383 have their own line editor and hence use raw mode all the time. With
384 those commands, rlwrap will appear to "do nothing". Therefore, if rl‐
385 wrap is in direct mode when the user presses ENTER for the first time
386 it will give a warning that it needs --always-readline to do anything
387 at all (warnings can be suppressed with the -n option)
388
393 If command writes a lot of output, it tends to be written (and read) in
394 "chunks". Not all chunks will end with a newline, and we need to dis‐
395 tinguish their last lines ("candidate prompts") from real prompts, es‐
396 pecially if we want to re-write ("cook") prompts. rlwrap solves this
397 (almost) by waiting a little, to see if there is more to come. "A lit‐
398 tle" is 40 msec by default, but this can be changed with the -w option.
399 Normally rlwrap writes the candidate prompt as soon as it is received,
400 replacing it with a "cooked" version after the wait time. This is
401 called "impatient" mode. If you don't like the flashing effect (which
402 can become annoying when you "cook" the prompt heavily) you can put rl‐
403 wrap in "patient mode" by specifying a negative value with -w (e.g. -w
404 -40). Rlwrap will then hold back the prompt and only print if after
405 cooking. If prompts always match some regular expression you can spec‐
406 ify "confident mode" with --only-cook='!<regexp>' (note the exclamation
407 mark). Then all candidate prompts that match (and only those) will be
408 cooked immediately. They will, however, not be "uncooked" if more out‐
409 put arrives, which can happen if they weren't prompts after all. Confi‐
410 dent mode doesn't work with a negative value for the -w option.
411
414 If and when rlwrap decides that it has a prompt, it will perform a num‐
415 ber of actions on it, depending on the given options: filtering (-z),
416 substituting (-S) and colouring (-p), in this order. The resulting
417 "cooked" prompt is then printed (after erasing the "raw" prompt, if
418 necessary)
419
421 Control + O
422 Accept the current line, but don't put it in the history list.
423 This action has a readline command name rlwrap-ac‐
424 cept-line-and-forget
425 Control + ^
427 Use an external editor (see RLWRAP_EDITOR below) to edit the
428 current input (this will only work if the -m option is set).
429 This action has a readline command name rlwrap-call-editor
430 (Not currently bound)
432 Any key (or key sequence, see below) can be bound to the read‐
433 line command rlwrap-direct-keypress. This key (or keys) will
434 then always be sent directly to command, even when rlwrap is not
435 in direct mode.
436 (Not currently bound)
438 Any key or key combination can be bound to the readline command
439 rlwrap-direct-prefix. This makes it possible to define multi-key
440 direct keypresses by defining their first key(s) as a 'direct
441 prefix'
442 (Not currently bound)
444 Any key can be bound to the readline command rlwrap-hotkey. This
445 key will then cause the current input line and the current his‐
446 tory to be filtered (cf. RlwrapFilter(3pm)) through the current
447 filter (hence be a no-op when there is no filter), which then
448 can re-write the input line, move the cursor and update the his‐
449 tory. After that, the user can still edit the resulting input.
450 (Not currently bound)
452 rlwrap-hotkey-without-history acts like rlwrap-hotkey, but the
453 history (which can be quite large) is not passed to the filter.
454 This is more efficient if the filter wouldn't do anything useful
455 with the history anyway.
456 The special keys were chosen for no other reason than that they are not
458 currently bound to any readline action. If you don't like them, (or
459 your window manager swallows them) they (and the other 4 commands) can
460 be re-bound more sensibly by including lines like the following in your
461 ~/.inputrc:
462 "\M-\C-m": rlwrap-accept-line-and-forget # ESC-ENTER to accept but keep out of history
464 "\C-x": rlwrap-call-editor # CTRL-x e to edit (multi-line) input in editor of your choice
465 $if erl # (only) for the Erlang shell:
466 "\C-g": rlwrap-direct-keypress # pass CTRL-g directly to enter 'user switch' command
467 $endif
468 "\C-t": rlwrap-direct-prefix # make it possible to define direct keypresses that start with CTRL-t ...
469 "\C-tx": rlwrap-direct-keypress # ... in that case: pass CTRL-t + x directly.
470 "\C-y": rlwrap-hotkey-without-history # CTRL-y to filter input line (and e.g. insert X selection)
471 cf. the readline(3) manpage. (NB: take care to not use keys that are
473 already caught by your window manager, or by the terminal driver, like
474 CTRL+S, as rlwrap will never see those)
475
477 RLWRAP_HOME:
478 directory in which the history and completion files are kept.
479 RLWRAP_EDITOR (or else EDITOR, or else VISUAL):
481 editor to use for multi-line input (and rlwrap-edit-history).
482 Example:
483 export RLWRAP_EDITOR="vi +%L"
485 export RLWRAP_EDITOR="vim '+call cursor(%L,%C)'"
486 export RLWRAP_EDITOR="emacs +%L:%C %F"
487 The first example above is the default; %L and %C are replaced by line
489 and column numbers corresponding to the cursor position in rlwrap's
490 edit buffer, %F is replaced by name of the (temporary) file. If %F is
491 not used, this name is put after the (expanded) $RLWAP_EDITOR
492 RLWRAP_FILTERDIR:
494 Any executable along your PATH can in theory be used as a fil‐
495 ter, but because filters have to follow a rather outlandish pro‐
496 tocol (cf. RlwrapFilter (3)) it is a good idea to keep them sep‐
497 arate. This is why rlwrap adds a special filter directory in
498 front of $PATH just before launching a filter. By default, this
499 is /usr/share/rlwrap/filters, but $RLWRAP_FILTERDIR is used in‐
500 stead, if set.
501
503 A number of signals are forwarded to command: HUP INT QUIT USR1 USR2
504 TERM and (by way of resizing command's terminal) WINCH. Some care is
505 taken to handle TSTP (usually a result of a CTRL-Z from the terminal)
506 sensibly - for example, after suspending rlwrap in the middle of a line
507 edit, continuing (by typing 'fg') will land you at the exact spot where
508 you suspended it.
509 A filter can be used to modify/ignore signals, or send output "out of
511 band" to the rlwrapped command.
512 Filters (except those that filter signals) that take more than 1 second
514 to respond can be interrupted by a CTRL-C from the terminal (although
515 rlwrap will not survive this)
516 If command changes the keystrokes that send a particular signal from
518 the keyboard (like emacs, which uses CTRL-G instead of CTRL-C) rlwrap
519 will do the same (but only after the next keystroke - use the --polling
520 option to make rlwrap more transparent in this respect)
521 When command is killed by a signal, rlwrap will clean up, reset its
523 signal handlers an then commit suicide by sending the same signal to
524 itself. This means that your shell sees the same exit status as it
525 would have seen without rlwrap.
526
529 When the standard input is not a terminal (or when run inside an emacs
530 buffer), editing input doesn't make sense, so rlwrap will ignore all
531 options and simply execute command in place of itself. When stdout (or
532 stderr) is not a terminal, rlwrap will re-open it to /dev/tty (the
533 users terminal) after it has started command, so that command's output
534 is redirected as expected, but keyboard input and rlwrap error messages
535 are still visible.
536 The upshot of this is that rlwrap command behaves more or less like
538 command when redirecting.
539
542 non-zero after a rlwrap error, or else command's exit status. rlwrap
543 will always leave the terminal in a tidy state, even after a crash.
544
546 rlwrap expects its history and completion files in $RLWRAP_HOME, but
547 uses .dotfiles in the user's home directory if this variable is not
548 set. This will quickly become messy if you use rlwrap for many differ‐
549 ent commands.
550 $RLWRAP_HOME/command_history, ~/.command_history
552 History for command (remember that command may be overridden by
553 the --command-name (or -C) option)
554 $RLWRAP_HOME/command_completions, ~/.command_completions
556 Per-user completion word list for command. rlwrap never writes
557 into this list, but one can use -l logfile and then -f logfile
558 to simulate the effect of a -r option that works across invoca‐
559 tions.
560 /usr/share/rlwrap/completions/command
562 System-wide completion word list for command. This file is only
563 consulted if the per-user completion word list is not found.
564 $INPUTRC, ~/.inputrc
566 Individual readline initialisation file (See readline [22m(3) for
567 its format). rlwrap sets its application name to command (this
568 can be overridden by the -C option), enabling different behav‐
569 iours for different commands. One could e.g. put the following
570 lines in ~/.inputrc:
571 $if coqtop
573 set show-all-if-ambiguous On
574 $endif
575 making rlwrap show all completions whenever it runs coqtop
577
579 Though it is flexible, delivers the goods (readline functionality), and
580 adheres to the Unix "many small tools" paradigm, rlwrap is a kludge. It
581 doesn'tknow anything about command's internal state, which makes con‐
582 text-sensitive completion impossible. Using the GNU Readline library
583 from within command is still by far the best option.
584 Also, as "it takes two to tango" there is no way for rlwrap to synchro‐
586 nise its internal state with command, resulting in a number of subtle
587 race conditions, where e.g. command may have changed the state of its
588 terminal before rlwrap has read command output that was written before
589 the state change. You will notice these races especially on a busy ma‐
590 chine and with heavy "cooking" and filtering, when suddenly (and unpre‐
591 dictably) prompts or command output are garbled or incorrectly
592 coloured.
593 rlwrap can try, but often fails to, handle prompts that contain control
595 characters (prompts, and the effect of -A and -t, can be analysed by
596 the filter dissect_prompt). If -A (--ansi-colour-aware) doesn't help,
597 a filter may be needed to clean up the prompt. Specifying --set-term-
598 name with a simpler, of even dumb, terminal may also help.
599
605 This manpage documents rlwrap version 0.45.2
606
608 The GNU Readline library (written by Brian Fox and Chet Ramey) does all
609 the hard work behind the scenes, the pty-handling code (written by Ge‐
610 off C. Wing) was taken practically unchanged from rxvt, and completion
611 word lists are managed by Damian Ivereigh's libredblack library. The
612 rest was written by Hans Lub (hanslub42@gmail.com).
613
615 readline(3), RlwrapFilter(3pm)
616 Fanuary 5, 2021 rlwrap(1)