1rlwrap(1)                   General Commands Manual                  rlwrap(1)
2
3
4

NAME

6       rlwrap - readline wrapper
7

SYNOPSIS

9       rlwrap [rlwrap-options] command ...
10

DESCRIPTION

12       rlwrap  runs the specified command, intercepting user input in order to
13       provide readline's line editing, persistent history and completion.
14
15       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
22       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

OPTIONS

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
36              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
40
41       -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
48       -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
56       -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
63       -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
70       -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
77       -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
82       -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
89              Specifying -f . will make rlwrap use the current history file as
90              a completion word list.
91
92       -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
99       -h, --help
100              Print a short help message.
101
102       -H, --history-filename file
103              Read  command  history  from  file  (and  write it back there if
104              --histsize >= 0)
105
106       -i, --case-insensitive
107              Ignore  case  when  completing  (filename   completion   remains
108              case-sensitive). This option has to come before any -f options.
109
110       -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
114       -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
119       -n, --no-warnings
120              Don't print warnings.
121
122       -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
129              This option needs /proc/command_pid/wchan, so it only works with
130              linux kernels configured with CONFIG_KALLSYMS.
131
132       -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
142       -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
146       -o, --one-shot
147              Send an EOF to command after accepting the first line of input
148
149       -O, --only-cook regexp
150              Only ever "cook" prompts that match regexp
151
152       -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
166       -P, --pre-given text
167              Start rlwrap with text in its edit buffer (this  will  automati‐
168              cally set the --always-readline option).
169
170       -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
176       -r, --remember
177              Put all words seen on in- and output on the completion list.
178
179       -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
184       -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
189       -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
193       -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
198       -U, --mirror-arguments
199              (linux only) Keep track of command's arguments as seen by the ps
200              (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
206       -v, --version
207              Print rlwrap version.
208
209       -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
222       -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
230       -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
242                  rlwrap -z 'filter args' command ...
243                  rlwrap -z 'pipeline filter1 ... : filter2 ... : ...' command ...
244
245              If this  command  line  contains  shell  metacharacters,  rlwrap
246              passes it to the system shell for parsing.
247

EXAMPLES

249       Run nc (netcat) with command-line editing and history
250          rlwrap nc
251
252       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
256       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
260       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
266       Get a list of all currently installed filters
267          rlwrap -z listing
268
269       Get help for the filter pipeto
270          rlwrap -z pipeto
271
272       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
277       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
282

DIRECT MODE AND READLINE MODE

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
294       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

PATIENT AND IMPATIENT MODE

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

COOKING PROMPTS

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

SPECIAL KEYS AND BINDABLE COMMANDS

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
331       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
336       (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
342       (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
347       (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
355       (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
361       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
367          "\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
376       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

ENVIRONMENT

381       RLWRAP_HOME:
382              directory in which the history and completion files are kept.
383
384       RLWRAP_EDITOR (or else EDITOR, or else VISUAL):
385              editor to use for multi-line  input  (and  rlwrap-edit-history).
386              Example:
387
388           export RLWRAP_EDITOR="vi +%L"
389           export RLWRAP_EDITOR="vim '+call cursor(%L,%C)'"
390           export RLWRAP_EDITOR="emacs +%L:%C %F"
391
392       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
397       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

SIGNALS

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
414       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
418       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
423       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
428

REDIRECTION

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
437       The upshot of this is that rlwrap command behaves  more  or  less  like
438       command when redirecting.
439
440

EXIT STATUS

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

FILES

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
451       $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
455       $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
460       /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
464       $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
471                 $if coqtop
472                     set show-all-if-ambiguous On
473                 $endif
474
475              making rlwrap show all completions whenever it runs coqtop
476

BUGS and LIMITATIONS

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
484       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
493       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
496       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
500
501

VERSION

503       This manpage documents rlwrap version 0.44
504

AUTHORS

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

SEE ALSO

514       readline(3), RlwrapFilter(3pm)
515
516
517
518
519
520
521
522
523
524
525
526                               Januari 19, 2021                      rlwrap(1)
Impressum