Provided by: bosh_0.6-8_amd64 bug

NAME

       bosh - Browsable Output SHell

SYNOPSIS

       bosh [OPTIONS] [CONFIGURATION] [CONFIGURATION OPTIONS]

DESCRIPTION

       bosh  takes  the  output  of a program or script and provides a curses interface to browse
       that output. A particular line of that output can be selected and actions can  be  defined
       and executed and make use of the that selected line.

USAGE

       CONFIGURATION  is the name of a bosh configuration file (see below), in which case that is
       loaded.

       If CONFIGURATION is absent, and bosh is invoked on the end of a pipe, it  will  read  from
       stdin.

       Bosh  now supports passing arguments to the CONFIGURATION. The arguments will be available
       in the standard way ($1...$9,$*,$@,etc).

       Bosh can be invoked as above, or as "interpreter", meaning it can invoked from  a  shebang
       (#!) line at the top of a script. This script would just be a bosh configuration file. See
       bops as an example, which should have come with bosh.

OPTIONS

       -h / --help
              show help and exit

       -v / --version
              show version and exit

       --autorefresh=N
              Automatically re-run command every N seconds.

       --cursorsize=N
              Set the cursor to N lines high.

       --cursormovement=N
              Set how much the cursor moves one an up/down keypress.

       --header=[N]
              Prevent the cursor from entering the first N rows of the output.

       --multilineseperator=STRING
              When an action is invoked and the cursor is multi-line, the lines selected will  be
              concatenated  together.   With this setting a separating string can be specified to
              be inserted between the lines.

       --preaction=COMMANDS
              A command or commands that will be run on the invocation of all actions, before the
              action  is  run.   This  allows  code  that  is a common for the actions to be only
              defined once. Preactions are simply prefixed onto the action  when  the  action  is
              invoked.  This  means you will need to include a separating character (eg ;) at the
              end of preaction.

       --refresh=[0,1]
              A value of 1 means that bosh will re-run the command after an action is performed.

       --uservars=N
              Set the number of user variables ( of the form $BOSHVARx ) available. See the  USER
              VARIABLES section below.

CONFIGURATION FILES

       Bosh  configs  are  fairly  simple.  Firstly  you  need a line which tells bosh the actual
       program to execute to show it it's buffer -

              command=ps x

       It could also be a chain of commands (bash) -

              command=for i in *; do echo $i; done

       Or it can spread it over multiple lines for readability with a \ (must be at  the  end  of
       line!) -

              command=for i in * \

              do \

              echo $i \

              done

       Or now even better, bosh supports blocks delimited by {{ and }} -
              command{{

              for i in *

              do

              echo $i

              done

              }}

       These can be used with all options and actions.

       Command  line arguments given to bosh after the COMMAND parameter are available and can be
       used as follows -

              command=ps $*

       This would allow the user to specify the format of ps when invoking bosh.

       Commands can also set BOSHERR.  When execution of the command finishes, bosh will exit and
       display the value of BOSHERR if it has been set.

              command=if [ -z "$1" ] \

              then \

                       BOSHERR="usage: $BOSHCONF [SECTION] NAME" \

                       return 1 \

              fi \

              man $*

       This will mean bosh exits immediately if no arguments are passed on the command line. Note
       the use of return rather than exit.

       After the command option, you can specify any  of  the  options  specified  above  in  the
       OPTIONS section, but without the -- prefix -

              header=4

              refresh=1

ACTIONS

       Basic actions are defined as -

              KEY=command

       eg:

              k=kill $(echo $BOSH | cut -f1 -d' ')

              9=kill -9 $(echo $BOSH | cut -f1 -d' ')

       Or, using the preaction setting (see above) -

              preaction=PID=$(echo $BOSH | cut -f1 -d' ');

              k=kill $PID

              9=kill -9 $PID

       The  keys  available are a-z,0-9 and enter. Bosh keys are not case sensitive, so A= is the
       same as a=.

       $BOSH is an environment variable containing the currently selected line(s) in bosh. It  is
       set  when  the action key is invoked. This is how information is passed to the actions. In
       the example above, the PID is extracted from the currently selected line of the ps  output
       using cut, which can then be passed to the kill command.

   ACTIONS WITH OUTPUT
       For  basic  actions  such  as kill, which has no output to stdout, the above definition is
       sufficient. However, bosh can now intercept the output of actions and place  that  in  the
       bosh window. These are defined as follows -

              KEY=[.]command
       Or,

       eg:

              l=[.]/usr/sbin/lsof -p $PID

       Assuming  the preaction is used above, this action will use lsof to show in bosh a list of
       files that process $PID has open. In this situation, the output of the original command is
       lost, and replaced with the output of the action.

       Alternatively an action can be defined -
              KEY=[>]command

       In  this  situation,  bosh  is  like  a  web  browser, in that this output (lsof) will not
       override the current buffer, but create a new buffer - You can  get  then  move  back  and
       forward  through  these buffers with the left and right arrow keys. At this stage, actions
       are only available in the original buffer.

       The other possibility is that an action may be required that has output that isn't  to  be
       shown in the bosh window, such as other curses-based applications. So the following syntax
       will make bosh end curses mode when this action is invoked.

              KEY=[!]command

       eg: If the bosh window contained a list of files, an action like this  could  be  used  to
       load that file in pico.

              e=[!]pico $BOSH

   ACTION PARAMETERS
       Actions  can  now have a prompt for user input before performing the action.  The value is
       available to the action using the $BOSHPARAM variable.

       eg: Using the ps example above, with PID preaction -

              s=[!:signal] kill -s $BOSHPARAM $PID

       When this action is called, bosh will ask for user input with the prompt signal:  .   Once
       this has been entered, the action will run.

BOSH* VARIABLES:

       In  addition  to  $BOSH  ,  $BOSHPARAM  and  $BOSHERR (all explained above), the following
       variables available to actions -

       $BOSHPID
              Process ID of bosh itself

       $BOSHPPID
              Parent process ID of bosh (eg: the shell you ran bosh from)

   USER VARIABLES
       User variables are variables to be set and used by commands and actions. They are  of  the
       form  $BOSHVARx.   When  the  command or action is run and sets a user variable, bosh will
       store the contents when that command or action has finished.  This allows the values to be
       used  by  subsequent actions. To make use of these, you must first set the uservars to the
       number you need (eg: uservars=1 will give you BOSHVAR1, uservars=10 will give you BOSHVAR1
       thru BOSHVAR10).

SHELLS

       Currently  bosh  only supports bash as the shell that it spawns for executing the commands
       and actions.  Support for other shells and languages will hopefully  be  included  in  the
       future.

EXAMPLE CONFIGURATION:

       Included  with  bosh  should  be a simple configuration named bops. It uses ps as the main
       command, and allows you to kill the selected process or view its open files (using  lsof).
       This  is  where  the  above examples are taken from. The original inspiration for bosh was
       being able to kill processes easily in this manner.

       To run bops, type -

              $ ./bops

       This invokes bosh through the shebang at the top (assuming the path is set correctly).

       Or to run it the traditional way -

              $ ./bosh ./bops

KEYS

       UP/DOWN
              cursor up/down

       LEFT/RIGHT
              buffer forward/back

       ^L     refresh screen

       ^O     run new command

       ^P     pipe buffer through a command, with the output of that pipe will become the buffer

       ^R     refresh program output (re-run the command)

       ^V     show the current configuration

       ^W     search

       ^N     repeat search

       ^X     exit

       F3     same as ^W

       F4     same as ^N

       F5     same as ^R

       F6     reload configuration

       F12    same as ^L

       |      same as ^P

STATUS BAR

       The status bar contains some further information about the current configuration. It shows
       with exit=num the last exit value of a command run in bosh. Furthermore a R indicates that
       bosh is running with refresh option activated. In the status bar there will be a countdown
       shown if the autorefresh option is set.

AUTHOR

       Alex Sisson (alexsisson@gmail.com)

HOMEPAGE

       Check for updates at http://bosh.sourceforge.net