Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, July 27, 2022

rlwrap (1)


rlwrap - readline wrapper


rlwrap [rlwrap-options] command ...


rlwrap(1)                   General Commands Manual                  rlwrap(1)

       rlwrap - readline wrapper

       rlwrap [rlwrap-options] command ...

       rlwrap  runs the specified command, intercepting user input in order to
       provide readline's line editing, persistent history and completion.

       rlwrap tries (and almost succeeds) to be completely transparent  -  you
       (or  your  shell)  shouldn't  notice any difference between command and
       rlwrap command - except the added readline  functionality,  of  course.
       This  should even hold true when you are re-directing, piping and send-
       ing signals from and to command, and when command manipulates its  ter-
       minal settings, working directory or (with the -U option) command line.

       There  are  many  options  to  add  (programmable)  completion,  handle
       multi-line input, colour and re-write prompts. If you don't  need  them
       (and  you  probably  don't),  you  can  skip  the rest of this manpage,
       although some of those options could make your command line quite a bit
       more comfortable...

       -a[password_prompt], --always-readline[=password_prompt]
              Always remain in "readline mode" (see below), regardless of com-
              mand's terminal settings.  If rlwrap "does nothing" this is  the
              option  to  use,  as command is apparently already doing its own
              line editing.  NB: With this option, rlwrap will echo (and save)
              passwords, unless you give command's password prompt as an argu-

              The argument is optional; if given, it has to directly follow  a
              short  option  without  an intervening space (-aPassword:) and a
              long option with an equals sign (--always-readline=Password:).

              The -N (--no-children) option can  be  used  to  avoid  wrapping
              pagers  and  editors  called from command; this should make them
              much more usable

       -A[!], --ansi-colour-aware[=!]
              Prompts that use colour, or use other CSI codes to e.g. set win-
              dow  titles or enable bracketed-paste will confuse rlwrap, espe-
              cially at the end of long input lines. This option will  usually
              (but  by  no  means  always)  make rlwrap better behaved in such

              Giving '!' as an argument will  make  rlwrap  remove  all  color
              codes from the prompt.

              The  argument is optional; if given, it has to directly follow a
              short option without an  intervening  space  (-A!)  and  a  long
              option with an equals sign (--ansi-colour-aware=!).

       -b, --break-chars list_of_characters
              Consider  the  specified characters word-breaking (whitespace is
              always word-breaking). This  determines  what  is  considered  a
              "word", both when completing and when building a completion word
              list from files specified by -f options following  (not  preced-
              ing!) it.  Default list (){}[],'+-=&^%$#@";|\ Unless -c is spec-
              ified, / and . (period) are included in the default list.

       -c, --complete-filenames
              Complete filenames (filename completion  is  always  case-sensi-
              tive,  even  with  the  -i  option). On Linux, OS X, FreeBSD and
              Solaris rlwrap will keep track of command's  working  directory,
              so  that  relative  filenames  will  be  completed  as one would

       -C, --command-name command_name|N
              Use command_name instead of command to determine  the  names  of
              history  and  completion  files,  and to initialise readline (as
              specified in ~/.inputrc). A numeric argument N >  0  means:  use
              the Nth argument counting backwards from the end of the argument

       -D, --history-no-dupes n
              How aggressively to weed out duplicate entries  from  the  input
              history.   If n = 0, all inputs are kept in the history list, if
              n = 1 (this is the default) consecutive duplicates  are  dropped
              from  the  list,  while n = 2 will make rlwrap drop all previous
              occurrences of the current input from the list.

       -e, --extra-char-after-completion char
              By default, rlwrap appends a space after any inserted completion
              text.  Use  this  option to change this to '' (don't insert any-
              thing) or some other character.

       -E, --always-echo
              By default, rlwrap avoids displaying passwords by echoing  '***'
              whenever  the  client  clears  the  ECHO flag on its input. This
              option will make rlwrap ignore this ECHO flag  and  always  echo
              the user's input. (-aPassword: will still work as expected)

       -f, --file file
              Split  file  into words (using the default word-breaking charac-
              ters, or those specified by --break-chars), and add them to  the
              completion  word  list. This option can be given more than once,
              and adds to the  default  completion  list  in  $RLWRAP_HOME  or

              Specifying -f . will make rlwrap use the current history file as
              a completion word list.

       -g, --forget-matching regexp
              Forget (i.e. never put into the history list) input  lines  that
              match  the POSIX 1003.2 regular expression regexp.  The match is
              always case-insensitive. perl-style character classes like  '\d'
              are  not  recognised,  use  '[:digit:]'.  For more about regular
              expressions, see regex (7)

       -h, --help
              Print a short help message.

       -H, --history-filename file
              Read command history from file  (and  write  it  back  there  if
              --histsize >= 0)

       -i, --case-insensitive
              Ignore   case   when  completing  (filename  completion  remains
              case-sensitive). This option has to come before any -f options.

       -I, --pass-sigint-as-sigterm
              Send a TERM signal to command when an INT is received (e.g. when
              you press CTRL-C).

       -l, --logfile file
              When  in  readline  mode,  append  command's  output  (including
              echo'ed user input) to  file  (creating  file  when  it  doesn't

       -m[newline_substitute], --multi-line[=newline_substitute]
              Enable  multi-line  input using a "newline substitute" character
              sequence (" \ ", [space-backslash-space]  by  default).  Newline
              substitutes  are translated to newlines before sending the input
              to command. With this option, you can call  an  external  editor
              $RLWRAP_EDITOR   on   the  (expanded)  current  input  with  the
              rlwrap_call_editor key  (CTRL-^  by  default)  The  argument  is
              optional;  if  given,  it  has to directly follow a short option
              without an intervening space (-m';;') and a long option with  an
              equals sign (--multi-line=';;').

       -M, --multi-line-ext .ext
              Call  multi-line-editor  on temporary files with filename exten-
              sion .ext (useful for e.g. automatic syntax colouring)

       -n, --no-warnings
              Don't print warnings.

       -N, --no-children
              When rlwrap is invoked with the --always-readline  option,  edi-
              tors  and  pagers  that  are called by the client will be pretty
              unusable, as they will see your keypresses  only  if  you  press
              ENTER.  rlwrap -N will avoid this problem by switching to direct
              mode if it thinks command is waiting for one of its children.

       -o, --one-shot
              Send an EOF to command after accepting the first line of input

       -O, --only-cook regexp
              Only ever "cook" prompts that match regexp, which  can  be  pre-
              ceded by  '!', meaning that  all matching candidate prompts will
              be cooked immediately ("confident mode").

       -p[colour], --prompt-colour[=colour]
              Use one of the colour names black,  red,  green,  yellow,  blue,
              cyan,   purple   (=magenta)  or  white,  or  an  ANSI-conformant
              <colour_spec> to colour any  prompt  displayed  by  command.  An
              uppercase  colour  name (Yellow or YELLOW ) gives a bold prompt.
              Prompts that already contain (colour) escape sequences or one of
              the  readline  "ignore  markers"  (ASCII  0x01 and 0x02) are not
              coloured. This option implies --ansi-colour-aware.  You can also
              use  a  colour  spec of the form <attr>;<fg>[;<bg>], for example
              -p'1;31' will give a bold red prompt on the  current  background
              (this  is  the  default  when  no argument is given). Google for
              'ANSI color' to learn more about colour codes.  The argument  is
              optional;  if  given,  it  has to directly follow a short option
              without an intervening space (-p'Red') and a long option with an
              equals sign (--prompt-colour='Red').

       -P, --pre-given text
              Start  rlwrap  with text in its edit buffer (this will automati-
              cally set the --always-readline option).

       -q, --quote-characters list_of_characters
              Assume that the given characters act as quotes, e.g. when match-
              ing  parentheses. Take care to escape the list properly for your
              shell (example: -q "\"'", which happens to be the default, or -q
              "\"" which will be better for lisp-like input)

       -r, --remember
              Put all words seen on in- and output on the completion list.

       -R, --renice
              Make  rlwrap  nicer than command (cf nice (1)). This may prevent
              rlwrap from interrupting command to display a prompt  when  com-
              mand is still "thinking" about what to output next.

       -s, --histsize N
              Limit the history list to N entries, truncating the history file
              (default: 300). A negative size -N (even -0) means the  same  as
              N, but treats the history file as read-only.

       -S, --substitute-prompt prompt
              Substitute the specified prompt for command's own prompt. Mainly
              useful when command doesn't have a prompt.

       -t, --set-term-name name
              Set command's TERM to name. Programs that  confuse  rlwrap  with
              fancy  screen control codes can sometimes be tamed by specifying
              -t dumb

       -U, --mirror-arguments
              (linux only) Keep track of command's arguments as seen by the ps
              (1)  command, and mirror them in rlwrap's own arguments This can
              be useful for  commands  that  overwrite  command-line  password
              arguments  that  would be exposed by rlwrap without this option.
              The mirroring takes place after the first user input,  or  every
              few milliseconds, if you use the --polling option.

       -v, --version
              Print rlwrap version.

       -w, --wait-before-prompt timeout
              In  order  to  determine  if  command's last output is a prompt,
              rlwrap waits timeout milliseconds after receiving it.  Only when
              no  more  output  has  arrived, it is cooked (coloured, filtered
              and/or replaced by a  substitute  prompt)  and  displayed  as  a
              prompt.   Before  this  the prompt is displayed "uncooked". Most
              users won't notice, but heavy cookers can  prepend  the  timeout
              with  a  minus sign, making rlwrap hold back the prompt until it
              has been cooked ("patient mode"). This will prevent flashing  of
              the  prompt,  but  it will also interfere with long output lines
              and make switches from direct to readline  mode  less  reliable.
              Default timeout: 40 ms

       -W, --polling
              EXPERIMENTAL:  Wake up every timeout millisecs, where timeout is
              the same as for the -w (--wait-before-prompt) option, 40  ms  by
              default.  This  is used to sense the slave's interrupt character
              and ISIG flag and to adjust stdin's  terminal  settings  accord-
              ingly,  even  before  you press a key. Try this option e.g. when
              CTRL-C acts differently on command with, and without, rlwrap.

       -z, --filter some_filter
              Use some_filter to change rlwrap's  behaviour.  Filters  can  be
              used  to  keep  certain  input out of the history, to change the
              prompt, to implement simple  macros,  programmable  hotkeys  for
              e.g.  fuzzy  history search, and programmable completion. rlwrap
              comes with a perl and a python module  to  make  filter  writing
              easy. (cf. RlwrapFilter(3pm) for the perl module, the python one
              is very similar) A number of example filters  are  installed  in
              the directory /usr/share/rlwrap/filters.

                  rlwrap -z listing

              lists all currently installed filters, while

                  rlwrap -z some_filter

              displays information about some_filter

              If  some_filter needs arguments, you should quote the whole fil-
              ter command line:

                  rlwrap -z 'some_filter args' command ...
                  rlwrap -z 'pipeline filter1 ... : filter2 ... : ...' command ...

              If this  command  line  contains  shell  metacharacters,  rlwrap
              passes it to the system shell for parsing.

              As  filters  have  to  follow a special protocol, shell commands
              like sed and grep cannot be used as rwlrap  filters.  They  can,
              however, be converted into filters by the makefilter filter:

                  rlwrap -z 'makefilter egrep -i --color "error|$"' command

              will color all occurrences of "error" (or "Error")  in command's
              output, while

                  rlwrap  -z  'makefilter  --message-type   history   sed   -e
              s"/whisky/lemonade/"' command

              sanitises  your  drinking  history. Both filters can be combined
              using the pipeline filter, of course.

       Run nc (netcat) with command-line editing and history
          rlwrap nc

       Wrap smbclient (which uses readline itself), keep passwords out of  the
       history  and  don't  interfere  with  pagers (like less) called by smb-
          rlwrap -aPassword: -N smbclient //PEANUT/C

       Wrap sensitive_app, hide password from ps (if  sensitive_app  does  so)
       and keep all input that starts with a space out of history:
          rlwrap -g '^ ' -U sensitive_app --password MySeCrEt

       Wrap  gauche  (a  Scheme  interpreter)  with a bold blue prompt, enable
       multi-line editing (using .scm as filename extension)  and  don't  con-
       sider  single  quotes as quotes (so that the parentheses in e.g. (print
       'q) match)
          rlwrap -pBlue -m -M .scm -q'"' gosh

       Wrap sqlite3, use the pipeto filter to be able to pipe  the  output  of
       SQL commands through grep and/or less, complete (case-insensitively) on
       the SQL keywords in 'sql_words'
          rlwrap -a -z pipeto -i -f sql_words sqlite3 contacts.db

       In a shell script, use rlwrap in 'one-shot' mode as a  replacement  for
          order=$(rlwrap -pYellow -S 'Your                         pizza? ' -H
          past_orders -P Margherita -o cat)

       Most simple console commands put your terminal either in "cooked" or in
       "raw"  mode.  In cooked mode the terminal will wait until you press the
       ENTER key before handing the entire line to the program,  in  raw  mode
       every key you press is handed down immediately. In cooked mode you gen-
       erally can use the backspace key, but not the arrow keys, to edit  your

       When  you  rlwrap  command, rlwrap will run it a in a separate session,
       under its own (controlling) "pseudo-terminal" (pty), and  monitor  this
       pty  to see whether it is in raw, or in cooked mode. In the first case,
       rlwrap will copy all input and output directly between command and your
       terminal  ("direct mode"). In the second case, rlwrap will use readline
       to edit your input ("readline mode"), and monitor  command's  output  -
       every  last line that doesn't end with a newline is a potential prompt.
       How it handles  such  a  candidate  prompt  depends  on  its  being  in
       "patient" or "impatient" mode, see below.

       Simple  console commands use cooked mode whenever they want whole input
       lines, and raw mode when they want single  keypresses.  Those  are  the
       progams  for  which rlwrap is most useful.  More sophisticated commands
       have their own line editor and hence use raw mode all the  time.   With
       those  commands,  rlwrap  will  appear  to "do nothing".  Therefore, if
       rlwrap is in direct mode when the user presses ENTER for the first time
       it  will  give a warning that it needs --always-readline to do anything
       at all (warnings can be suppressed with the -n option)

       If command writes a lot of output, it tends to be written (and read) in
       "chunks".  Not  all chunks will end with a newline, and we need to dis-
       tinguish their last lines  ("candidate  prompts")  from  real  prompts,
       especially  if we want to re-write ("cook") prompts. rlwrap solves this
       (almost) by waiting a little, to see if there is more to come. "A  lit-
       tle" is 40 msec by default, but this can be changed with the -w option.
       Normally rlwrap writes the candidate prompt as soon as it is  received,
       replacing  it  with  a  "cooked"  version  after the wait time. This is
       called "impatient" mode. If you don't like the flashing  effect  (which
       can  become  annoying  when  you "cook" the prompt heavily) you can put
       rlwrap in "patient mode" by specifying a negative value with  -w  (e.g.
       -w  -40). Rlwrap will then hold back the prompt and only print if after
       cooking.  If prompts always match some regular expression you can spec-
       ify "confident mode" with --only-cook='!<regexp>' (note the exclamation
       mark).  Then all candidate prompts that match (and only those) will  be
       cooked  immediately. They will, however, not be "uncooked" if more out-
       put arrives, which can happen if they weren't prompts after all. Confi-
       dent mode doesn't work  with a negative value for the -w option.

       If and when rlwrap decides that it has a prompt, it will perform a num-
       ber of actions on it, depending on the given options:  filtering  (-z),
       substituting  (-S)  and  colouring  (-p),  in this order. The resulting
       "cooked" prompt is then printed (after erasing  the  "raw"  prompt,  if

       Control + O
              Accept  the  current line, but don't put it in the history list.
              This     action     has     a     readline     command      name

       Control + ^
              Use  an  external  editor  (see RLWRAP_EDITOR below) to edit the
              current input (this will only work if the  -m  option  is  set).
              This action has a readline command name rlwrap-call-editor

       (Not currently bound)
              Any  key  (or key sequence, see below) can be bound to the read-
              line command rlwrap-direct-keypress. This  key  (or  keys)  will
              then always be sent directly to command, even when rlwrap is not
              in direct mode.

       (Not currently bound)
              Any key or key combination can be bound to the readline  command
              rlwrap-direct-prefix. This makes it possible to define multi-key
              direct keypresses by defining their first key(s)  as  a  'direct

       (Not currently bound)
              Any key can be bound to the readline command rlwrap-hotkey. This
              key will then cause the current input line and the current  his-
              tory  to be filtered (cf. RlwrapFilter(3pm)) through the current
              filter (hence be a no-op when there is no  filter),  which  then
              can re-write the input line, move the cursor and update the his-
              tory. After that, the user can still edit the resulting input.

       (Not currently bound)
              rlwrap-hotkey-without-history acts like rlwrap-hotkey,  but  the
              history  (which can be quite large) is not passed to the filter.
              This is more efficient if the filter wouldn't do anything useful
              with the history anyway.

       The special keys were chosen for no other reason than that they are not
       currently bound to any readline action. If you  don't  like  them,  (or
       your  window manager swallows them) they (and the other 4 commands) can
       be re-bound more sensibly by including lines like the following in your

          "\M-\C-m":  rlwrap-accept-line-and-forget         # ESC-ENTER to accept but keep out of history
          "\C-x":     rlwrap-call-editor                    # CTRL-x e to edit (multi-line) input in editor of your choice
           $if erl                                          # (only) for the Erlang shell:
              "\C-g": rlwrap-direct-keypress                # pass CTRL-g directly to enter 'user switch' command
           "\C-t":    rlwrap-direct-prefix                  # make it possible to define direct keypresses that start with CTRL-t ...
           "\C-tx":   rlwrap-direct-keypress                # ... in that case: pass CTRL-t + x directly.
           "\C-y":    rlwrap-hotkey-without-history         # CTRL-y to filter input line (and e.g. insert X selection)

       cf.  the  readline(3)  manpage. (NB: take care to not use keys that are
       already caught by your window manager, or by the terminal driver,  like
       CTRL+S, as rlwrap will never see those)

              directory in which the history and completion files are kept.

       RLWRAP_EDITOR (or else EDITOR, or else VISUAL):
              editor  to  use  for multi-line input (and rlwrap-edit-history).

           export RLWRAP_EDITOR="vi +%L"
           export RLWRAP_EDITOR="vim '+call cursor(%L,%C)'"
           export RLWRAP_EDITOR="emacs +%L:%C %F"

       The first example above is the default; %L and %C are replaced by  line
       and  column  numbers  corresponding  to the cursor position in rlwrap's
       edit buffer, %F is replaced by name of the (temporary) file.  If %F  is
       not used, this name is put after the (expanded) $RLWAP_EDITOR

              Any  executable  along your PATH can in theory be used as a fil-
              ter, but because filters have to follow a rather outlandish pro-
              tocol (cf. RlwrapFilter (3)) it is a good idea to keep them sep-
              arate. This is why rlwrap adds a  special  filter  directory  in
              front  of $PATH just before launching a filter. By default, this
              is  /usr/share/rlwrap/filters,  but  $RLWRAP_FILTERDIR  is  used
              instead, if set.

       A  number  of  signals are forwarded to command: HUP INT QUIT USR1 USR2
       TERM and (by way of resizing command's terminal) WINCH.  Some  care  is
       taken  to  handle TSTP (usually a result of a CTRL-Z from the terminal)
       sensibly - for example, after suspending rlwrap in the middle of a line
       edit, continuing (by typing 'fg') will land you at the exact spot where
       you suspended it.

       A filter can be used to modify/ignore signals, or send output  "out  of
       band" to the rlwrapped command.

       Filters (except those that filter signals) that take more than 1 second
       to respond can be interrupted by a CTRL-C from the  terminal  (although
       rlwrap will not survive this)

       If  command  changes  the keystrokes that send a particular signal from
       the keyboard (like emacs, which uses CTRL-G instead of  CTRL-C)  rlwrap
       will do the same (but only after the next keystroke - use the --polling
       option to make rlwrap more transparent in this respect)

       When command is killed by a signal, rlwrap will  clean  up,  reset  its
       signal  handlers  an  then commit suicide by sending the same signal to
       itself.  This means that your shell sees the same  exit  status  as  it
       would have seen without rlwrap.

       When  the standard input is not a terminal (or when run inside an emacs
       buffer), editing input doesn't make sense, so rlwrap  will  ignore  all
       options  and simply execute command in place of itself. When stdout (or
       stderr) is not a terminal, rlwrap will  re-open  it  to  /dev/tty  (the
       users  terminal) after it has started command, so that command's output
       is redirected as expected, but keyboard input and rlwrap error messages
       are still visible.

       The  upshot  of  this  is that rlwrap command behaves more or less like
       command when redirecting.

       non-zero after a rlwrap error, or else command's  exit  status.  rlwrap
       will always leave the terminal in a tidy state, even after a crash.

       rlwrap  expects  its  history and completion files in $RLWRAP_HOME, but
       uses .dotfiles in the user's home directory if  this  variable  is  not
       set.  This will quickly become messy if you use rlwrap for many differ-
       ent commands.

       $RLWRAP_HOME/command_history, ~/.command_history
              History for command (remember that command may be overridden  by
              the --command-name (or -C) option)

       $RLWRAP_HOME/command_completions, ~/.command_completions
              Per-user  completion  word list for command. rlwrap never writes
              into this list, but one can use -l logfile  and then -f  logfile
              to  simulate the effect of a -r option that works across invoca-

              System-wide completion word list for command. This file is  only
              consulted if the per-user completion word list is not found.

       $INPUTRC, ~/.inputrc
              Individual  readline  initialisation  file (See readline (3) for
              its format). rlwrap sets its application name to  command  (this
              can  be  overridden by the -C option), enabling different behav-
              iours for different commands.  One could e.g. put the  following
              lines in ~/.inputrc:

                 $if coqtop
                     set show-all-if-ambiguous On

              making rlwrap show all completions whenever it runs coqtop

       Though it is flexible, delivers the goods (readline functionality), and
       adheres to the Unix "many small tools" paradigm, rlwrap is a kludge. It
       doesn'tknow  anything  about command's internal state, which makes con-
       text-sensitive completion impossible. Using the  GNU  Readline  library
       from within command is still by far the best option.

       Also, as "it takes two to tango" there is no way for rlwrap to synchro-
       nise its internal state with command, resulting in a number  of  subtle
       race  conditions,  where e.g. command may have changed the state of its
       terminal before rlwrap has read command output that was written  before
       the  state  change.  You  will  notice these races especially on a busy
       machine and with heavy "cooking"  and  filtering,  when  suddenly  (and
       unpredictably)  prompts  or  command  output are garbled or incorrectly

       rlwrap can try, but often fails to, handle prompts that contain control
       characters  (prompts,  and  the effect of -A and -t, can be analysed by
       the filter dissect_prompt). If  -A (--ansi-colour-aware) doesn't  help,
       a  filter may be needed to clean up the prompt.  Specifying --set-term-
       name with a simpler, of even dumb, terminal may also help.

       This manpage documents rlwrap version 0.45

       The GNU Readline library (written by Brian Fox and Chet Ramey) does all
       the  hard  work  behind  the  scenes, the pty-handling code (written by
       Geoff C. Wing) was taken practically unchanged from rxvt,  and  comple-
       tion  word  lists are managed by Damian Ivereigh's libredblack library.
       The rest was written by Hans Lub (hanslub42@gmail.com).

       See attributes(7) for descriptions of the following attributes:

       |Availability   | shell/rlwrap     |
       |Stability      | Uncommitted      |

       readline(3), RlwrapFilter(3pm)

       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source  was  downloaded  from   https://github.com/hanslub42/rlwrap/ar-

       Further information about this software can be found on the open source
       community website at https://github.com/hanslub42/rlwrap.

                                Fanuary 5, 2021                      rlwrap(1)