--- name: "bashrun" section: "1" platform: "linux" package: "bashrun" version: "0.16.1-6" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/bashrun" --- # bashrun(1) X11 application launcher based on bash ## NAME bashrun - X11 application launcher based on bash ## SYNOPSIS **bashrun** *\[options\]* ## DESCRIPTION **bashrun** is a simple application launcher for X11. It runs a bash session within a small XTerminal window, conveniently providing all the common bash features like readline, tab completion and history, while adding more features like bookmarks, regexp based handlers, dictionary lookups and google search queries. **bashrun** provides two basic modes of operation, depending on whether [**xdotool**(1)](/xdotool/1.md) is installed on the system. If [**xdotool**(1)](/xdotool/1.md) is available, the terminal hosting the bash session will be kept running in the background, hidden from display. Invoking **bashrun** or **bashrun --show** will show and focus the window; after issuing a command, the terminal window will be hidden from display again. This method reduces startup time and saves system resources. If [**xdotool**(1)](/xdotool/1.md) is not installed, a new instance is created on each invocation, immediately terminating after running the first command. ## OPTIONS - \-v, --version **print version information** - \-h, --help **print usage information** - \-d, --debug **start in debug mode** If [**xdotool**(1)](/xdotool/1.md) is available, the following options control a running bashrun instance from subsequent invocations. Note that if no previous bashrun instance is found, options **--show**, **--toggle**, **--restart**, **--su** and **--debug** will start a new bashrun session. - \--show **map the window and focus it** - \--hide **unmap the window** - \--toggle **toggle window visibility** - \--exit **terminate an existing bashrun process** - \--restart **restart bashrun (required to apply configuration file changes)** - \--su command **run command with root privileges. Brings up the bashrun terminal for** password entry. - \--remote type \ key \ ... **Type text into bashrun and invoke key sequences remotely. See the** **key** command in [**xdotool**(1)](/xdotool/1.md) for the syntax of **\**. - \--wid **print the terminal's window id** - \--wait **wait until terminal window is unmapped** - \--debug **toggle debug mode** ## RUNNING COMMANDS Running simple commands is straightforward. The shell will perform the usual expansions and the resulting command is handled and launched according to the user requested action and preferences. Multiple commands separated by **;** are successively handled in the same manner. If commands are separated by a pipe symbol (**\|**) or by the logical operators **\|\|** or **&&** then bashrun's behavior will substantially differ from the normal shell behavior. To the bashrun shell, every simple command in a compound statement will appear as though it immediately returns success. This means that separating commands with **&&** or **\|** is effectively equivalent to using **;**. Separating commands with **\|\|** will prevent the execution of commands on the right hand side of the expression. To circumvent this behavior, the characters **;**, **&** and **\|** can be escaped with a backslash character (**\\**). Please note that in this case terminal rules are only applied based on the command name of the first command. To illustrate, a command like **$ cat textfile \| wc -l \** will fail to work as intended and instead page the output of both commands in separate terminals, with no pipe established between the commands. You will need to use **$ cat textfile \\\| wc -l \** to page the number of lines in **textfile** in a single terminal window as intended. Editing multiple lines does not work in bashrun. If you happen to forget a closing quote on your commandline, bashrun will ask you to press **C-c**. Your last history line may be bogus after this. To run commands in the context of the bashrun shell session instead of having them handled by bashrun, use the **\** action (default: **M-w**). ## KEYBOARD CONFIGURATION FILE Keybindings can be configured in the keyboard configuration file *$XDG\_CONFIG\_HOME/bashrun/keys*. This file contains **keymap** directives and **keybinding** definitions. The **keymap** directive chooses the readline keymap that subsequent **keybinding** definitions will be bound to. The syntax is **KEYMAP \** where **\** is either *emacs*, *vi-insert* or *vi-command*. The syntax for **keybinding** definitions is **\ \ \[\\]** where **\** is the name of the bashrun action (see **ACTIONS** below), **keyseq** is a valid **readline**(1) key sequence, and **\** is an optional human-readable name for the key sequence (used to display the keybindings to the user). Please note that all key sequences beginning with **C-x\[0-9\]** as well as the literal characters **\\\\201** up to **\\\\209** are reserved for internal use and can not be used. Lines beginning with **#** are comments and will be ignored. ## ACTIONS This section lists all actions that can be bound to key sequences. Use the **\** action (default: **F1**) in the to show the current keybindings. - quit **Quit bashrun. Terminates the bashrun shell session.** - abort **Hide the window (using xdotool) or quit.** - pass **Execute command in the context of the bashrun shell session, bypasses** command handling. - run **Execute the command.** - term-run **Execute the command in a terminal.** - term-hold **Execute the command in a terminal and hold.** - term-page **Execute the command in a terminal and page output using** **PAGER**. - su-run **Execute the command with root privileges. You will be prompted for the** password first. - su-term-run **Execute the command with root priviledges in a terminal.** - su-term-hold **Execute the command with root privileges in a terminal and hold.** - su-term-page **Execute the command with root privileges in a terminal and page** output using **PAGER**. - show-manual **Show the manual page for the command in a terminal.** - show-info **Show the info page for the command in a terminal.** - show-help **Page help for bash builtin commands in terminal. Tries to show the** manual page if the command is not a bash builtin. - copy **Copy command output to clipboard (using xclip).** - copy-paste **Copy command output and paste it to window under the mouse cursor** (using xclip and xdotool). - filter **Pipe clipboard contents into command and copy output to cliboard (using xclip).** - filter-paste **Pipe clipboard contents into command and copy output to cliboard, then** paste to window under the mouse cursor (using xclip and xdotool). - browse **Browse words in BROWSER, see CONFIGURATION FILE** - google-search **Google words in BROWSER, see CONFIGURATION FILE** - dict-lookup **Look up words in dictionary, requires** [**dict**(1)](/dict/1.md) or similar. Use the config option **DICT\_CLIENT** to use a different client, see **CONFIGURATION FILE** - bashrun-bindings **Show the current keybindings in a terminal.** - bashrun-manual **Show this manual in a terminal.** - bashrun-handlers **Show current HANDLERS in a terminal.** - bashrun-debug **Toggle debugging messages on/off. Sets** **KEEP\_OPEN** and resizes the terminal to 80x24 if supported. - toggle-size **Toggle between "small" and "large" size (xterm, \*rxvt only). See** **CONFIGURATION FILE**. - resize-\[up\|down\|left\|right\] **Resize the terminal. (xterm, \*rxvt only)** ## CONFIGURATION FILE The user configuration file *$XDG\_CONFIG\_HOME/bashrun/rc* will be sourced as the rcfile for the bash session used by bashrun. Apart from the environment variables described here you can add anything that you would usually add to your *~/.bashrc* file. For example, you might want to add functions or aliases, bind additional function keys or simply source your existing *~/.bashrc* file. Please make sure that you don't interfere with the tty/bash settings and reserved keybindings used by bashrun. See **KEYBOARD CONFIGURATION FILE** and **ENVIRONMENT** or take a look at *$PREFIX/share/bashrun/bashrc*. **XTERM=\[xterm\|rxvt\|urxvt\|urxvtc\|mrxvt\|aterm\|mlterm\] (default: xterm)** The terminal to be used for bashrun. **XTERM\_OPTIONS=\[...\] (default: empty)** Additional commandline options to be passed to the terminal. **KEEP\_OPEN=\[yes\|no\] (default: no)** If set to "yes", the terminal won't be hidden after every command. Subsequent invocations of **bashrun** or **bashrun --show** will focus the terminal window, **\** or **bashrun --hide** will unfocus the window and give focus back to the previously focused application. **SMALL\_COLUMNS=n, SMALL\_LINES=n (default: 40x1)** Size of the terminal in the default "small" mode. **LARGE\_COLUMNS=n, LARGE\_LINES=n (default: 40x8)** Size of the terminal in "large" mode, toggled via **\** (xterm and \*rxvt only). **FGCOLOR=color, BGCOLOR=color (default: grey on black)** Foreground and background color of the terminal. Consult your terminal's documentation for possible values. **PS1=\[...\] (default: '\>')** Prompt string, see [**bash**(1)](/bash/1.md) **HISTCONTROL (default: ignoredups:erasedups)** History settings, see [**bash**(1)](/bash/1.md) **COMPLETION\_TYPE=\[complete\|menu-complete\|quiet-complete\] (default: menu-complete)** For **complete** and **menu-complete**, see [**bash**(1)](/bash/1.md). The **quiet-complete** mode will use **complete** and additionally set the following readline variables: page-completions off\ print-completions-horizontally on\ completion-query-items -1 The **quiet-complete** mode is useful if you want completion to behave like **complete** but without being interrupted by readline prompts. Although completions are actually printed you will effectively not see them in a one-line-terminal. **ALTERNATIVE\_COMPLETION\_TYPE=\[complete\|menu-complete\|quiet-complete\] (default: complete)** The completion type to switch to if LINES \>= COMPLETION\_THRESHOLD, see below. **COMPLETION\_THRESHOLD=\[num\_lines\] (default: LARGE\_LINES)** If the number of LINES in the terminal is equal or greater than this value, switch to ALTERNATIVE\_COMPLETION\_TYPE. If the value is less than 1, this feature is disabled. (Note: the default setup for these options results in using **menu-complete** in "small" mode and **complete** in "large" mode.) **USE\_EXTENDED\_BASH\_COMPLETION=\[yes\|no\] (default: no)** Whether to use extended bash completion. **EXTENDED\_BASH\_COMPLETION\_PATH=\[path\]** **(default: /etc/profile.d/bash\_completion.sh)** Path to a script enabling extended bash completion. Consult your distribution's documentation. **POST\_MAP\_COMMAND=\[command\] (default: not set)** Command to run directly after making the window visible via xdotool. E.g. you could set the transparency of the window to 75% using **transset -a 0.75** when running **xcompmgr**. **DICT\_CLIENT=\[command\] (default: dict --pager $PAGER)** Which dict client to use for the **\** action. Add your client to the TERMINAL\_RULES if neccessary. **DIRHANDLER=\[command\] (default: not set)** A command to be run when a path to a directory is entered and the directory is readable. The path will be passed as the first argument to the specified command. **BROWSER=\[command\] (default: firefox)** Browser to use for google search and default handlers (see below). **GOOGLE\_FALLBACK=\[yes\|no\] (default: no)** If set to **yes** bashrun will automatically google the commandline if it isn't executable or if it's not handled by **HANDLERS** or **DIRHANDLER** **TERMINAL\_RULES=('RUN:\[progs\]' 'PAGE:\[progs\]' 'HOLD:\[progs\]')** An array containing rule strings that define which programs should always be launched in a terminal window. Insert a space separated list of program names after the **:** into the string for the desired rule. Programs in the **RUN** rule are always launched in a terminal. Programs in the **PAGE** rule will have their output paged in **PAGER**. For programs in the **HOLD** rule the terminal is kept open after the program terminates. Example: TERMINAL\_RULES=(\ "RUN:watch top htop less man info ncftp links"\ "HOLD:ps su"\ "PAGE:echo ls which uname lsusb lshal lsmod fortune"\ ) **HANDLERS=(\[regexp handler\]...) (defaults: see below)** An array containing bash regular expressions and associated handler strings. If the commandline entered into bashrun is not executable (i.e. it's not a function, alias or a binary on **PATH**) then an attempt is made to successively match the commandline against the patterns contained in **HANDLERS**. If a pattern matches, either the handler string following the pattern will be used as the command to execute, with the commandline itself passed as the argument, or, if the regexp contains subpatterns within parenthesis, an attempt is made to substitute the occurrence of **$\[1-9\]** in the handler string with the contents of the corresponding subpattern match. The modified handler string is then used as the commandline without adding further arguments. If there are not enough subpattern matches to substitute every occurrence of **$\[0-9\]** in the handler string then the handler will not be executed and an error message will be issued to the user. The handler string may additionally be prefixed with a file test expression defining a series of file tests to be performed on the contents of the commandline prior to applying the handler. If any of these tests fail, the handler will not be applied. The test expression is a series of characters corresponding to the unary file test operators defined in section **CONDITIONAL EXPRESSIONS** of the [**bash**(1)](/bash/1.md) manual, terminated by **:**. File tests can be negated by prefixing them with a single **!**. E.g. a handler prefixed with **f!x:** will only be applied if the commandline is a path to a regular, non-executable file. For example, to define file associations for jpeg files you can use a pattern and handler like **'\\.jpe?g$' 'f!x:gimp'** This will open lines ending in **.jpg** or **.jpeg** using [**gimp**(1)](/gimp/1.md). The file test ensures that you can still type a line like **$ convert foo.tif foo.jpg** which will not be handled although it also ends in **.jpg**. This is because the test expression is applied to the complete line, so the **f!x** test will fail. To open lines beginning with **http** or **https** in your **BROWSER**, add a line like this to the **HANDLERS** array: **'^https?' "$BROWSER"** To implement web shortcuts similar to KDE's konqueror browser, use a pattern containing a subpattern, like this: **'^gg:(.+)'** and use a line like this as the handler string: **"$BROWSER 'http://www.google.com/search?q=\\$1'"** Bashrun will replace the **$1** part of the handler string with anything the user has entered after **gg:**. See the default user configuration file for more examples. if your handlers don't work as expected, turn on debug mode to see what is going on. The following handlers are setup by default if the default configuration file is being used or **HANDLERS** is not set in the user configuration file: - ^www, ^https? **Open lines beginning with www, http or https in BROWSER** - ^gg:(.+) **Google** - ^ggl:(.+) **Google using "I'm feeling lucky"** - ^fm:(.+) **Search for project on freshmeat.net** - ^sf:(.+) **Visit project page on sourceforge.net** - ^sfw:(.+) **Visit project website on sourceforge.net** - \\.jpe?g$ **Open JPEG files in gimp, using f!x as test expression** - ^ftp:(.+) **Start ncftp $1 in xterm** - ^\\?(.+) **Page $1 --help in xterm** - ^\\?\\?(.+) **Show man $1 in xterm** **BOOKMARKS=(\[bookmark\]...) (default: see example)** An array of strings that will be added to the possible command completions. Make sure there is a handler defined in **HANDLERS** for each of the strings used as bookmarks. Example: BOOKMARKS=(\ www.google.com\ www.archlinux.org\ www.slashdot.org\ www.linux.com\ http://bashrun.sourceforge.net\ ) **LOGFILE=\[path\] (default: /dev/null)** Command output (stdout and stderr) is appended to LOGFILE. If it doesn't exist, bashrun will attempt to create it. If it is not writeable, output is redirected to **/dev/null** instead. Logging is disabled for commands run with root privileges. ## FILES *$XDG\_CONFIG\_HOME/bashrun/rc* The user configuration file. If it does not exist, it will be created and initialized with the default configuration. *$XDG\_CONFIG\_HOME/bashrun/keys* The keyboard configuration file. If it does not exist, it will be created and initialized with the default keybindings. If [**xdotool**(1)](/xdotool/1.md) is used, bashrun needs to be restarted to make changes to these files take effect. If **XDG\_CONFIG\_HOME** is not set or empty, **~/.config** will be used instead. *$XDG\_DATA\_HOME/bashrun/history* The history file used by bashrun. If **XDG\_DATA\_HOME** is not set or empty, **~/.local/share** will be used instead. *$XDG\_CACHE\_HOME/bashrun/* Directory for temporary files created by bashrun. If **XDG\_CACHE\_HOME** is not set or empty, **~/.cache** will be used instead. ## ENVIRONMENT - X11 The Window manager properties **WM\_CLASS** and **WM\_NAME** are set to "bashrun". These properties can be used with your window manager's facilities to further configure the appearance of bashrun. Note that if you are using [**xdotool**(1)](/xdotool/1.md) it is recommended to make the bashrun window "sticky" to make sure it will always appear on the current desktop. - BASH The **extdebug** shell option is enabled. A trap on **DEBUG** is set each time a commandline is issued. The trap is disabled again after commandline processing to prevent it from interfering with interactive commandline editing. Sending **^D** (eof) on an empty line does not terminate the shell if [**xdotool**(1)](/xdotool/1.md) is being used. See [**stty**(1)](/stty/1.md) **XON/XOFF** flow control (Suspend/Resume terminal via **C-s** and **C-q**) is disabled. **C-s** will search forward in the history buffer (readline default) while **C-q** is bound to the **\** action when using the default keybindings. See [**stty**(1)](/stty/1.md) ## KNOWN ISSUES Some terminals require quoting of the commandline to be run. This means that running commandlines with lots quoting may fail for these terminals, although two levels of quoting should generally work. You can use the debug mode to find out exactly why and how a heavily quoted command fails. Only [**xterm**(1)](/xterm/1.md) and **\*rxvt**(1) support resizing using keybindings. xterm has occasionally been found to freeze during resizing, requiring at least a SIGTERM to close it. For XTerm, the **allowWindowOps** resource needs to be set to **True** to allow window resizing. This is enabled in the default configuration for xterm as of bashrun version 0.14. Note that setting **allowSendEvents** to **True** will forcefully disable **allowWindowOps** in XTerm. In order for meta keybindings (prefixed with **\\e** or **\\M-**) to work with the Alt or Meta key, the terminal needs to be configured to translate your meta key to an escape. For XTerm, this can be enabled by setting the **metaSendsEscape** resource to **True**. This is enabled in the default configuration for xterm as of bashrun version 0.14. For URxvt, the **meta8** resource needs to be set to **False** (which is the default setting for URxvt). ## BUGS Please report any bugs you may find using the email address below. Comments and suggestions are also welcome. ## AUTHOR Henning Bekel \ (english and german) ## CONTRIBUTORS - Daniel J. Griffiths (aka Ghost1227) \ **Sourceforge hosting, website design, ArchLinux packaging** - Shapeshifter **Suggestions, code, bug reports** - Bernard Walle **Bug reports, OpenSuse packaging** - Dieter Plaetinck **Bug reports** - Wouter Koersen **Suggestions, code** - Mathias Dahl **Suggestions, bug reports** - Reuben Thomas **Suggestions, bug reports** ## REFERENCES bashrun - http://bashrun.sourceforge.net xdotool - http://www.semicomplete.com/projects/xdotool dict - http://www.dict.org/ ## SEE ALSO [**Xorg**(1)](/Xorg/1.md), [**xterm**(1)](/xterm/1.md), [**xdotool**(1)](/xdotool/1.md), [**dict**(1)](/dict/1.md), [**stty**(1)](/stty/1.md), [**bash**(1)](/bash/1.md), [**readline**(3)](/readline/3.md)