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