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 (in the current session) of the current input from
95 the list.
96 -e, --extra-char-after-completion char
99 By default, rlwrap appends a space after any inserted completion
100 text. Use this option to change this to '' (don't insert any‐
101 thing) or some other character.
102 -E, --always-echo
105 By default, rlwrap avoids displaying passwords by echoing '***'
106 whenever the client clears the ECHO flag on its input. This op‐
107 tion will make rlwrap ignore this ECHO flag and always echo the
108 user's input. (-aPassword: will still work as expected)
109 -f, --file file
113 Split file into words (using the default word-breaking charac‐
114 ters, or those specified by --break-chars), and add them to the
115 completion word list. This option can be given more than once,
116 and adds to the default completion list in $RLWRAP_HOME or
117 /usr/share/rlwrap/completions.
118 Specifying -f . will make rlwrap use the current history file as
120 a completion word list.
121 -g, --forget-matching regexp
124 Forget (i.e. never put into the history list) input lines that
125 match the POSIX 1003.2 regular expression regexp. The match is
126 always case-insensitive. perl-style character classes like '\d'
127 are not recognised, use '[:digit:]'. For more about regular ex‐
128 pressions, see regex (7)
129 -h, --help
132 Print a short help message.
133 -H, --history-filename file
136 Read command history from file (and write it back there if
137 --histsize >= 0)
138 -i, --case-insensitive
141 Ignore case when completing (filename completion remains
142 case-sensitive). This option has to come before any -f options.
143 -I, --pass-sigint-as-sigterm
146 Send a TERM signal to command when an INT is received (e.g. when
147 you press CTRL-C).
148 -l, --logfile file
151 When in readline mode, append command's output (including
152 echo'ed user input) to file (creating file when it doesn't ex‐
153 ist).
154 -m[newline_substitute], --multi-line[=newline_substitute]
157 Enable multi-line input using a "newline substitute" character
158 sequence (" \ ", [space-backslash-space] by default). Newline
159 substitutes are translated to newlines before sending the input
160 to command. With this option, you can call an external editor
161 $RLWRAP_EDITOR on the (expanded) current input with the rl‐
162 wrap_call_editor key (CTRL-^ by default) The argument is op‐
163 tional; if given, it has to directly follow a short option with‐
164 out an intervening space (-m';;') and a long option with an
165 equals sign (--multi-line=';;').
166 -M, --multi-line-ext .ext
169 Call multi-line-editor on temporary files with filename exten‐
170 sion .ext (useful for e.g. automatic syntax colouring)
171 -n, --no-warnings
175 Don't print warnings.
176 -N, --no-children
179 When rlwrap is invoked with the --always-readline option, edi‐
180 tors and pagers that are called by the client will be pretty un‐
181 usable, as they will see your keypresses only if you press EN‐
182 TER. rlwrap -N will avoid this problem by switching to direct
183 mode if it thinks command is waiting for one of its children.
184 -o, --one-shot
187 Send an EOF to command after accepting the first line of input
188 -O, --only-cook regexp
190 Only ever "cook" prompts that match regexp, which can be pre‐
191 ceded by '!', meaning that all matching candidate prompts will
192 be cooked immediately ("confident mode").
193 -p[colour], --prompt-colour[=colour]
196 Use one of the colour names black, red, green, yellow, blue,
197 cyan, purple (=magenta) or white, or an ANSI-conformant
198 <colour_spec> to colour any prompt displayed by command. An up‐
199 percase colour name (Yellow or YELLOW ) gives a bold prompt.
200 Prompts that already contain (colour) escape sequences or one of
201 the readline "ignore markers" (ASCII 0x01 and 0x02) are not
202 coloured. This option implies --ansi-colour-aware. You can also
203 use a colour spec of the form <attr>;<fg>[;<bg>], for example
204 -p'1;31' will give a bold red prompt on the current background
205 (this is the default when no argument is given). Google for
206 'ANSI color' to learn more about colour codes. The argument is
207 optional; if given, it has to directly follow a short option
208 without an intervening space (-p'Red') and a long option with an
209 equals sign (--prompt-colour='Red').
210 -P, --pre-given text
213 Start rlwrap with text in its edit buffer (this will automati‐
214 cally set the --always-readline option).
215 -q, --quote-characters list_of_characters
218 Assume that the given characters act as quotes, e.g. when match‐
219 ing parentheses. Take care to escape the list properly for your
220 shell (example: -q "\"'", which happens to be the default, or -q
221 "\"" which will be better for lisp-like input)
222 -r, --remember
225 Put all words seen on in- and output on the completion list.
226 -R, --renice
229 Make rlwrap nicer than command (cf nice (1)). This may prevent
230 rlwrap from interrupting command to display a prompt when com‐
231 mand is still "thinking" about what to output next.
232 -s, --histsize N
235 Limit the history list to N entries, truncating the history file
236 (default: 300). A negative size -N (even -0) means the same as
237 N, but treats the history file as read-only.
238 -S, --substitute-prompt prompt
241 Substitute the specified prompt for command's own prompt. Mainly
242 useful when command doesn't have a prompt.
243 -t, --set-term-name name
246 Set command's TERM to name. Programs that confuse rlwrap with
247 fancy screen control codes can sometimes be tamed by specifying
248 -t dumb
249 -U, --mirror-arguments
252 (linux only) Keep track of command's arguments as seen by the ps
253 [1m(1) command, and mirror them in rlwrap's own arguments This can
254 be useful for commands that overwrite command-line password ar‐
255 guments that would be exposed by rlwrap without this option. The
256 mirroring takes place after the first user input, or every few
257 milliseconds, if you use the --polling option.
258 -v, --version
261 Print rlwrap version.
262 -w, --wait-before-prompt timeout
265 In order to determine if command's last output is a prompt, rl‐
266 wrap waits timeout milliseconds after receiving it. Only when
267 no more output has arrived, it is cooked (coloured, filtered
268 and/or replaced by a substitute prompt) and displayed as a
269 prompt. Before this the prompt is displayed "uncooked". Most
270 users won't notice, but heavy cookers can prepend the timeout
271 with a minus sign, making rlwrap hold back the prompt until it
272 has been cooked ("patient mode"). This will prevent flashing of
273 the prompt, but it will also interfere with long output lines
274 and make switches from direct to readline mode less reliable.
275 Default timeout: 40 ms
276 -W, --polling
279 EXPERIMENTAL: Wake up every timeout millisecs, where timeout is
280 the same as for the -w (--wait-before-prompt) option, 40 ms by
281 default. This is used to sense the slave's interrupt character
282 and ISIG flag and to adjust stdin's terminal settings accord‐
283 ingly, even before you press a key. Try this option e.g. when
284 CTRL-C acts differently on command with, and without, rlwrap.
285 -z, --filter some_filter
288 Use some_filter to change rlwrap's behaviour. Filters can be
289 used to keep certain input out of the history, to change the
290 prompt, to implement simple macros, programmable hotkeys for
291 e.g. fuzzy history search, and programmable completion. rlwrap
292 comes with a perl and a python module to make filter writing
293 easy. (cf. RlwrapFilter(3pm) for the perl module, the python one
294 is very similar) A number of example filters are installed in
295 the directory /usr/share/rlwrap/filters.
296 rlwrap -z listing
298 lists all currently installed filters, while
300 rlwrap -z some_filter
302 displays information about some_filter
304 If some_filter needs arguments, you should quote the whole fil‐
307 ter command line:
308 rlwrap -z 'some_filter args' command ...
310 rlwrap -z 'pipeline filter1 ... : filter2 ... : ...' command ...
311 If this command line contains shell metacharacters, rlwrap
314 passes it to the system shell for parsing.
315 As filters have to follow a special protocol, shell commands
317 like sed and grep cannot be used as rwlrap filters. They can,
318 however, be converted into filters by the makefilter filter:
319 rlwrap -z 'makefilter egrep -i --color "error|$"' command
321 will color all occurrences of "error" (or "Error") in command's
323 output, while
324 rlwrap -z 'makefilter --message-type history sed -e
326 s"/whisky/lemonade/"' command
327 sanitises your drinking history. Both filters can be combined
329 using the pipeline filter, of course.
330
334 Run nc (netcat) with command-line editing and history
335 rlwrap nc
336 Wrap smbclient (which uses readline itself), keep passwords out of the
338 history and don't interfere with pagers (like less) called by smb‐
339 client.
340 rlwrap -aPassword: -N smbclient //PEANUT/C
341 Wrap sensitive_app, hide password from ps (if sensitive_app does so)
343 and keep all input that starts with a space out of history:
344 rlwrap -g '^ ' -U sensitive_app --password MySeCrEt
345 Wrap gauche (a Scheme interpreter) with a bold blue prompt, enable
347 multi-line editing (using .scm as filename extension) and don't con‐
348 sider single quotes as quotes (so that the parentheses in e.g. (print
349 'q) match)
350 rlwrap -pBlue -m -M .scm -q'"' gosh
351 Wrap sqlite3, use the pipeto filter to be able to pipe the output of
353 SQL commands through grep and/or less, complete (case-insensitively) on
354 the SQL keywords in 'sql_words'
355 rlwrap -a -z pipeto -i -f sql_words sqlite3 contacts.db
356 In a shell script, use rlwrap in 'one-shot' mode as a replacement for
358 read
359 order=$(rlwrap -pYellow -S 'Your pizza? ' -H past_or‐
360 ders -P Margherita -o cat)
361
364 Most simple console commands put your terminal either in "cooked" or in
365 "raw" mode. In cooked mode the terminal will wait until you press the
366 ENTER key before handing the entire line to the program, in raw mode
367 every key you press is handed down immediately. In cooked mode you gen‐
368 erally can use the backspace key, but not the arrow keys, to edit your
369 input.
370 When you rlwrap command, rlwrap will run it a in a separate session,
372 under its own (controlling) "pseudo-terminal" (pty), and monitor this
373 pty to see whether it is in raw, or in cooked mode. In the first case,
374 rlwrap will copy all input and output directly between command and your
375 terminal ("direct mode"). In the second case, rlwrap will use readline
376 to edit your input ("readline mode"), and monitor command's output -
377 every last line that doesn't end with a newline is a potential prompt.
378 How it handles such a candidate prompt depends on its being in "pa‐
379 tient" or "impatient" mode, see below.
380 Simple console commands use cooked mode whenever they want whole input
382 lines, and raw mode when they want single keypresses. Those are the
383 progams for which rlwrap is most useful. More sophisticated commands
384 have their own line editor and hence use raw mode all the time. With
385 those commands, rlwrap will appear to "do nothing". Therefore, if rl‐
386 wrap is in direct mode when the user presses ENTER for the first time
387 it will give a warning that it needs --always-readline to do anything
388 at all (warnings can be suppressed with the -n option)
389
394 If command writes a lot of output, it tends to be written (and read) in
395 "chunks". Not all chunks will end with a newline, and we need to dis‐
396 tinguish their last lines ("candidate prompts") from real prompts, es‐
397 pecially if we want to re-write ("cook") prompts. rlwrap solves this
398 (almost) by waiting a little, to see if there is more to come. "A lit‐
399 tle" is 40 msec by default, but this can be changed with the -w option.
400 Normally rlwrap writes the candidate prompt as soon as it is received,
401 replacing it with a "cooked" version after the wait time. This is
402 called "impatient" mode. If you don't like the flashing effect (which
403 can become annoying when you "cook" the prompt heavily) you can put rl‐
404 wrap in "patient mode" by specifying a negative value with -w (e.g. -w
405 -40). Rlwrap will then hold back the prompt and only print if after
406 cooking. If prompts always match some regular expression you can spec‐
407 ify "confident mode" with --only-cook='!<regexp>' (note the exclamation
408 mark). Then all candidate prompts that match (and only those) will be
409 cooked immediately. They will, however, not be "uncooked" if more out‐
410 put arrives, which can happen if they weren't prompts after all. Confi‐
411 dent mode doesn't work with a negative value for the -w option.
412
415 If and when rlwrap decides that it has a prompt, it will perform a num‐
416 ber of actions on it, depending on the given options: filtering (-z),
417 substituting (-S) and colouring (-p), in this order. The resulting
418 "cooked" prompt is then printed (after erasing the "raw" prompt, if
419 necessary)
420
422 Control + O
423 Accept the current line, but don't put it in the history list.
424 This action has a readline command name rlwrap-ac‐
425 cept-line-and-forget
426 Control + ^
428 Use an external editor (see RLWRAP_EDITOR below) to edit the
429 current input (this will only work if the -m option is set).
430 This action has a readline command name rlwrap-call-editor
431 (Not currently bound)
433 Any key (or key sequence, see below) can be bound to the read‐
434 line command rlwrap-direct-keypress. This key (or keys) will
435 then always be sent directly to command, even when rlwrap is not
436 in direct mode.
437 (Not currently bound)
439 Any key or key combination can be bound to the readline command
440 rlwrap-direct-prefix. This makes it possible to define multi-key
441 direct keypresses by defining their first key(s) as a 'direct
442 prefix'
443 (Not currently bound)
445 Any key can be bound to the readline command rlwrap-hotkey. This
446 key will then cause the current input line and the current his‐
447 tory to be filtered (cf. RlwrapFilter(3pm)) through the current
448 filter (hence be a no-op when there is no filter), which then
449 can re-write the input line, move the cursor and update the his‐
450 tory. After that, the user can still edit the resulting input.
451 (Not currently bound)
453 rlwrap-hotkey-without-history acts like rlwrap-hotkey, but the
454 history (which can be quite large) is not passed to the filter.
455 This is more efficient if the filter wouldn't do anything useful
456 with the history anyway.
457 The special keys were chosen for no other reason than that they are not
459 currently bound to any readline action. If you don't like them, (or
460 your window manager swallows them) they (and the other 4 commands) can
461 be re-bound more sensibly by including lines like the following in your
462 ~/.inputrc:
463 "\M-\C-m": rlwrap-accept-line-and-forget # ESC-ENTER to accept but keep out of history
465 "\C-x": rlwrap-call-editor # CTRL-x e to edit (multi-line) input in editor of your choice
466 $if erl # (only) for the Erlang shell:
467 "\C-g": rlwrap-direct-keypress # pass CTRL-g directly to enter 'user switch' command
468 $endif
469 "\C-t": rlwrap-direct-prefix # make it possible to define direct keypresses that start with CTRL-t ...
470 "\C-tx": rlwrap-direct-keypress # ... in that case: pass CTRL-t + x directly.
471 "\C-y": rlwrap-hotkey-without-history # CTRL-y to filter input line (and e.g. insert X selection)
472 cf. the readline(3) manpage. (NB: take care to not use keys that are
474 already caught by your window manager, or by the terminal driver, like
475 CTRL+S, as rlwrap will never see those)
476
478 RLWRAP_HOME:
479 directory in which the history and completion files are kept.
480 RLWRAP_EDITOR (or else EDITOR, or else VISUAL):
482 editor to use for multi-line input (and rlwrap-edit-history).
483 Example:
484 export RLWRAP_EDITOR="vi +%L"
486 export RLWRAP_EDITOR="vim '+call cursor(%L,%C)'"
487 export RLWRAP_EDITOR="emacs +%L:%C %F"
488 The first example above is the default; %L and %C are replaced by line
490 and column numbers corresponding to the cursor position in rlwrap's
491 edit buffer, %F is replaced by name of the (temporary) file. If %F is
492 not used, this name is put after the (expanded) $RLWAP_EDITOR
493 RLWRAP_FILTERDIR:
495 Any executable along your PATH can in theory be used as a fil‐
496 ter, but because filters have to follow a rather outlandish pro‐
497 tocol (cf. RlwrapFilter (3)) it is a good idea to keep them sep‐
498 arate. This is why rlwrap adds a special filter directory in
499 front of $PATH just before launching a filter. By default, this
500 is /usr/share/rlwrap/filters, but $RLWRAP_FILTERDIR is used in‐
501 stead, if set.
502
504 A number of signals are forwarded to command: HUP INT QUIT USR1 USR2
505 TERM and (by way of resizing command's terminal) WINCH. Some care is
506 taken to handle TSTP (usually a result of a CTRL-Z from the terminal)
507 sensibly - for example, after suspending rlwrap in the middle of a line
508 edit, continuing (by typing 'fg') will land you at the exact spot where
509 you suspended it.
510 A filter can be used to modify/ignore signals, or send output "out of
512 band" to the rlwrapped command.
513 Filters (except those that filter signals) that take more than 1 second
515 to respond can be interrupted by a CTRL-C from the terminal (although
516 rlwrap will not survive this)
517 If command changes the keystrokes that send a particular signal from
519 the keyboard (like emacs, which uses CTRL-G instead of CTRL-C) rlwrap
520 will do the same (but only after the next keystroke - use the --polling
521 option to make rlwrap more transparent in this respect)
522 When command is killed by a signal, rlwrap will clean up, reset its
524 signal handlers an then commit suicide by sending the same signal to
525 itself. This means that your shell sees the same exit status as it
526 would have seen without rlwrap.
527
530 When the standard input is not a terminal (or when run inside an emacs
531 buffer), editing input doesn't make sense, so rlwrap will ignore all
532 options and simply execute command in place of itself. When stdout (or
533 stderr) is not a terminal, rlwrap will re-open it to /dev/tty (the
534 users terminal) after it has started command, so that command's output
535 is redirected as expected, but keyboard input and rlwrap error messages
536 are still visible.
537 The upshot of this is that rlwrap command behaves more or less like
539 command when redirecting.
540
543 non-zero after a rlwrap error, or else command's exit status. rlwrap
544 will always leave the terminal in a tidy state, even after a crash.
545
547 rlwrap expects its history and completion files in $RLWRAP_HOME, but
548 uses .dotfiles in the user's home directory if this variable is not
549 set. This will quickly become messy if you use rlwrap for many differ‐
550 ent commands.
551 $RLWRAP_HOME/command_history, ~/.command_history
553 History for command (remember that command may be overridden by
554 the --command-name (or -C) option)
555 $RLWRAP_HOME/command_completions, ~/.command_completions
557 Per-user completion word list for command. rlwrap never writes
558 into this list, but one can use -l logfile and then -f logfile
559 to simulate the effect of a -r option that works across invoca‐
560 tions.
561 /usr/share/rlwrap/completions/command
563 System-wide completion word list for command. This file is only
564 consulted if the per-user completion word list is not found.
565 $INPUTRC, ~/.inputrc
567 Individual readline initialisation file (See readline (3) for
568 its format). rlwrap sets its application name to command (this
569 can be overridden by the -C option), enabling different behav‐
570 iours for different commands. One could e.g. put the following
571 lines in ~/.inputrc:
572 $if coqtop
574 set show-all-if-ambiguous On
575 $endif
576 making rlwrap show all completions whenever it runs coqtop
578
580 Though it is flexible, delivers the goods (readline functionality), and
581 adheres to the Unix "many small tools" paradigm, rlwrap is a kludge. It
582 doesn't know anything about command's internal state, which makes con‐
583 text-sensitive completion impossible. Using the GNU Readline library
584 from within command is still by far the best option.
585 Also, as "it takes two to tango" there is no way for rlwrap to synchro‐
587 nise its internal state with command, resulting in a number of subtle
588 race conditions, where e.g. command may have changed the state of its
589 terminal before rlwrap has read command output that was written before
590 the state change. You will notice these races especially on a busy ma‐
591 chine and with heavy "cooking" and filtering, when suddenly (and unpre‐
592 dictably) prompts or command output are garbled or incorrectly
593 coloured.
594 rlwrap can try, but often fails to, handle prompts that contain control
596 characters (prompts, and the effect of -A and -t, can be analysed by
597 the filter dissect_prompt). If -A (--ansi-colour-aware) doesn't help,
598 a filter may be needed to clean up the prompt. Specifying --set-term-
599 name with a simpler, of even dumb, terminal may also help.
600
606 This manpage documents rlwrap version 0.46.1
607
609 The GNU Readline library (written by Brian Fox and Chet Ramey) does all
610 the hard work behind the scenes, the pty-handling code (written by Ge‐
611 off C. Wing) was taken practically unchanged from rxvt, and completion
612 word lists are managed by Damian Ivereigh's libredblack library. The
613 rest was written by Hans Lub (hanslub42@gmail.com).
614
616 readline(3), RlwrapFilter(3pm)
617 October 20, 2022 rlwrap(1)