Compose shell commands to build interactive terminal applications
Alternatives To Rat
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Ohmyzsh156,988132 days ago1December 07, 2014633mitShell
🙃 A delightful community-driven (with 2,100+ contributors) framework for managing your zsh configuration. Includes 300+ optional plugins (rails, git, macOS, hub, docker, homebrew, node, php, python, etc), 140+ themes to spice up your morning, and an auto-update tool so that makes it easy to keep up with the latest updates from the community.
14 hours ago1,544mitC++
The new Windows Terminal and the original Windows console host, all in the same place!
18 hours ago232otherMarkdown
📚 Collaborative cheatsheets for console commands
Bat40,3481352 days ago37September 10, 2022177apache-2.0Rust
A cat(1) clone with wings.
18 days ago114mitPython
the only cheat sheet you need
Lazygit33,632216 hours ago209July 18, 2022443mitGo
simple terminal UI for git commands
Httpie27,0181,64542a day ago55May 06, 2022143bsd-3-clausePython
🥧 HTTPie for Terminal — modern, user-friendly command-line HTTP client for the API era. JSON support, colors, sessions, downloads, plugins & more.
Awesome Shell26,944
8 days ago82cc0-1.0
A curated list of awesome command-line frameworks, toolkits, guides and gizmos. Inspired by awesome-php.
2 days ago24May 29, 202278apache-2.0Rust
A simple, fast and user-friendly alternative to 'find'
Modern Unix25,548
2 months ago83
A collection of modern/faster/saner alternatives to common unix commands.
Alternatives To Rat
Select To Compare

Alternative Project Comparisons


Compose shell commands to build terminal applications

Join the chat at https://gitter.im/rat-chat/Lobby GoDoc Build Status


Rat was developed as part of an effort to build a tig-like application with very little opinionated UI logic, delegating instead to the capabilities of shell commands like git log with its --pretty and --graph options.

Shell commands are executed and the output is captured and displayed in pagers. Configurable annotators parse through the output, adding annotations that can be acted upon to run other shell commands.

Getting Started



$ go get github.com/ericfreese/rat
$ go build && go install


Rat is configured through a file ratrc in your home config directory ($XDG_CONFIG_HOME/rat, ~/.config/rat by default).

Rat pagers can be opened in one or more "modes". A mode is a configuration of "annotators" and "key bindings":

  • Annotators will look through the content of the pager for special bits of text that actions can be taken on. These bits of text are called "annotations". Each annotation has a start, an end, a class, and a value.
  • Key bindings define actions that can be taken on annotations.


First you'll need to set up some keybindings. Add the following to your ratrc and modify as desired:

bindkey C-r reload
bindkey j   cursor-down
bindkey k   cursor-up
bindkey C-e scroll-down
bindkey C-y scroll-up
bindkey C-d page-down
bindkey C-u page-up
bindkey g,g cursor-first-line
bindkey S-g cursor-last-line
bindkey S-j parent-cursor-down
bindkey S-k parent-cursor-up
bindkey q   pop-pager
bindkey S-q quit
bindkey M-1 show-one
bindkey M-2 show-two
bindkey M-3 show-three

ctrl+c will always quit.

Mode Definitions

The mode keyword starts a mode definition.

mode <name>

Annotator Definitions

Inside of a mode definition, the annotate keyword starts an annotation definition.

mode <name>
  annotate <type> <class> -- <options>
  • type: The annotator type. Can be "match", "regex", or "external".
  • class: The class to apply to any annotations that this annotator finds.
  • options:
    • If type is "match", this should be a shell command that outputs newline-delimited strings that the annotator will search for.
    • If type is "regex", this should define a regular expression to search for (Golang regular expressions are supported).
    • If type is "external", this should be the name of an executable located in ~/.config/rat/annotators/ that will be executed and sent the content of the pager via STDIN. The executable should print annotations to STDOUT in a specific binary format:
      • Start: Byte offset from the beginning of STDIN (64-bit little-endian unsigned integer)
      • End: Byte offset from the beginning of STDIN (64-bit little-endian unsigned integer)
      • Value length: Length of found value string in bytes (64-bit little-endian unsigned integer)
      • Value string: String of above-specified length (UTF-8 encoded)

Keybinding Definitions

The bindkey keyword starts a keybinding definition.

mode <name>
  bindkey <key> [<annotation-classes>] [<new-pager-mode>] -- <action>

bindkey <key> <action>
bindkey <key> <new-pager-mode> -- <cmd>
  • key: A key combination that will trigger this action when pressed. Modifiers are added with C- and S-. See lib/key_event.go for a list of supported named keys.
  • action: A named action to run when the key is pressed. See action.go for a list of available actions.
  • annotation-classes: This action will only be triggered if annotations of these classes are present on the current line. If omitted, keybinding will work anywhere in the pager. These should be comma-delimited.
  • new-pager-mode: If the action will create a new pager, this defines the mode(s) to use when creating that pager.
  • cmd: A shell command to run when the specified key combination is pressed. Annotation values will be exported to the command process as variables named for their annotation class. The default is to open a new pager showing the output of the shell command, but several special prefixes can be used to specify different actions to be taken:
    • !: Do not open a new pager. Execute the command and reload the current pager.
    • ?!: Like !, but confirm with the user first (will have to press 'y' for yes or 'n' for no).
    • >: Like the default, open a new pager with the contents of the shell command, but also set up a parent-child relationship so that the parent cursor can be moved up and down from inside the child pager with the ParentCursorUp and ParentCursorDown commands.

Note: Keybindings that are not inside of a mode definition will always be available and do not have the special prefix behavior described above.

Source configurations from separate files

The source keyword imports configuration rules from another file.

source <file>
  • file: The path (relative to the rat config directory) to a file that contains valid rat configuration instructions


Add the following to your ratrc to build a simple file viewer/manager:

mode files
  # Find all files (not directories) in the current directory and
  # annotate with the class "file".
  annotate match file -- ls -a1p | grep -v /

  # When the cursor is on a line with an annotation of class "file" and
  # the `enter` key is pressed, run `cat` with the value of the
  # annotation (the filename) and display the output in a new pager with
  # mode "preview". 
  bindkey enter file preview -- >cat $file

  # When the cursor is on a line with an annotation of class "file" and
  # the `e` key is pressed, open the selected file in vim.
  bindkey e     file         -- !vim $file

  # When the cursor is on a line with an annotation of class "file" and
  # Shift + `x` is pressed, delete the file if the user confirms it.
  bindkey S-x   file         -- ?!rm $file

Run rat --mode files --cmd 'ls -al' to try it out. You should see the output of ls -al. Move your cursor to a line with a regular file on it and press Enter to view its contents. Try out the other keybindings. Try tweaking some things.

See examples/ directory for more configuration examples.



rat [--mode=<mode>] [--cmd=<command>]

--mode defaults to default.

If --cmd is not provided, rat will read from STDIN.



Dependencies are managed using glide.


This project is licensed under MIT license. For the full text of the license, see the LICENSE file.

Popular Terminal Projects
Popular Command Line Projects
Popular Command Line Interface Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Command Line