# bottom [![Build Status](https://travis-ci.com/ClementTsang/bottom.svg?token=1wvzVgp94E1TZyPNs8JF&branch=master)](https://travis-ci.com/ClementTsang/bottom) [![crates.io link](https://img.shields.io/crates/v/bottom.svg)](https://crates.io/crates/bottom) [![tokei](https://tokei.rs/b1/github/ClementTsang/bottom?category=code)](https://github.com/ClementTsang/bottom) [![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-) A cross-platform graphical process/system monitor with a customizable interface and a multitude of features. Supports Linux, macOS, and Windows. Inspired by both [gtop](https://github.com/aksakalli/gtop) and [gotop](https://github.com/cjbassi/gotop). ![Quick demo recording showing off searching, maximizing, and process killing.](assets/summary_and_search.gif) _Theme based on [gruvbox](https://github.com/morhetz/gruvbox) (see [sample config](./sample_configs/demo_config.toml))._ Recorded on version 0.2.0. This documentation is relevant to version 0.3.0. Please refer to [release branch](https://github.com/ClementTsang/bottom/tree/release/README.md) or [crates.io](https://crates.io/crates/bottom) for the most up-to-date _release_ version. ## Table of Contents - [Installation](#installation) - [Manual](#manual) - [Cargo](#cargo) - [AUR](#aur) - [Debian (and Debian-based)](#debian) - [Homebrew](#homebrew) - [Scoop](#scoop) - [Chocolatey](#chocolatey) - [Usage](#usage) - [Flags](#flags) - [Options](#options) - [Keybindings](#keybindings) - [General](#general) - [CPU bindings](#cpu-bindings) - [Process bindings](#process-bindings) - [Process search bindings](#process-search-bindings) - [Features](#features) - [Process filtering](#process-filtering) - [Zoom](#zoom) - [Maximizing](#maximizing) - [Config files](#config-files) - [Config flags](#config-flags) - [Theming](#theming) - [Layout](#layout) - [Compatibility](#compatibility) - [Contribution](#contribution) - [Thanks](#thanks) ## Installation Note that binaries are built on the stable version of Rust, and I mainly test and release for 64-bit. ### Manual Clone from this repo or from [Releases](https://github.com/ClementTsang/bottom/releases), and build with `cargo build --release`. You may also want to strip the binary after. ### Cargo ```bash cargo install bottom ``` ### AUR ```bash yay bottom # If you instead want the binary version: yay bottom-bin ``` ### Debian A `.deb` file is provided on each [release](https://github.com/ClementTsang/bottom/releases/latest): ```bash curl -LO https://github.com/ClementTsang/bottom/releases/download/0.2.2/bottom_0.2.2_amd64.deb sudo dpkg -i bottom_0.2.2_amd64.deb ``` ### Homebrew ```bash brew tap clementtsang/bottom brew install bottom # If you need to be more specific, use: brew install clementtsang/bottom/bottom ``` ### Scoop ```bash scoop install bottom ``` ### Chocolatey ```bash choco install bottom # Version number may be required for newer releases: choco install bottom --version=0.2.2 ``` ## Usage Run using `btm`. ### Flags ``` -h, --help Prints help information, including flags and options -a, --avg_cpu Shows the average CPU usage in addition to per-core -m, --dot-marker Uses a dot marker instead of the default braille marker -c, --celsius Displays the temperature type in Celsius [default] -f, --fahrenheit Displays the temperature type in Fahrenheit -k, --kelvin Displays the temperature type in Kelvin -l, --left_legend Displays the CPU legend to the left rather than the right -u, --current_usage Sets process CPU usage to be based on current total CPU usage -g, --group Groups together processes with the same name by default -S, --case_sensitive Search defaults to matching cases -W, --whole Search defaults to searching for the whole word -R, --regex Search defaults to using regex -s, --show_disabled_data Shows disabled CPU entries in the CPU legend -b, --basic Enables basic mode, removing charts and condensing data ``` ### Options ``` -r, --rate Set the refresh rate in milliseconds [default: 1000] -C, --config Use the specified config file; if it does not exist it is automatically created -t, --default_time_value Sets the default time interval for charts in milliseconds [default: 60000] -d, --time_delta Sets the default amount each zoom in/out action changes by in milliseconds [default: 15000] ``` ### Keybindings #### General | | | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `q`, `Ctrl-c` | Quit bottom | | `Esc` | Close dialog windows, search, widgets, or exit maximized mode | | `Ctrl-r` | Reset display and any collected data | | `f` | Freeze/unfreeze updating with new data | | `Ctrl`-arrow key
`Shift`-arrow key
`H/J/K/L` | Move to a different widget (on macOS some keybindings may conflict) | | `Up`,`k` | Scroll up in tables | | `Down`, `j` | Scroll down in tables | | `?` | Open help menu | | `gg`, `Home` | Jump to the first entry of a table | | `Shift-g`, `End` | Jump to the last entry of a table | | `Enter` | Maximize widget | | `+` | Zoom in on a chart | | `-` | Zoom out on a chart | | `=` | Reset zoom | | Mouse scroll | Table: Scrolls through the list
Chart: Zooms in or out by scrolling up or down respectively | #### CPU bindings | | | | ------- | -------------------------------------------- | | `/` | Open filtering for showing certain CPU cores | | `Space` | Toggle enabled/disabled cores | | `Esc` | Exit filtering mode | #### Process bindings | | | | ------------- | ---------------------------------------------------------- | | `dd` | Kill the selected process | | `c` | Sort by CPU usage, press again to reverse sorting order | | `m` | Sort by memory usage, press again to reverse sorting order | | `p` | Sort by PID name, press again to reverse sorting order | | `n` | Sort by process name, press again to reverse sorting order | | `Tab` | Group/un-group processes with the same name | | `Ctrl-f`, `/` | Open process search widget | #### Process search bindings | | | | ------------ | -------------------------------------------- | | `Tab` | Toggle between searching by PID or name | | `Esc` | Close the search widget (retains the filter) | | `Ctrl-a` | Skip to the start of the search query | | `Ctrl-e` | Skip to the end of the search query | | `Alt-c`/`F1` | Toggle matching case | | `Alt-w`/`F2` | Toggle matching the entire word | | `Alt-r`/`F3` | Toggle using regex | ## Features As yet _another_ process/system visualization and management application, bottom supports the typical features: - CPU, memory, and network usage visualization - Display information about disk capacity and I/O per second - Display temperatures from sensors - Process management (process killing _is_ all you need, right?) It also aims to be: - Lightweight - Cross-platform - supports Linux, Windows, and macOS In addition to these things, bottom also currently has the following features: ### Process filtering On any process widget, hit `/` to bring up a search bar. If your layout has multiple process widgets, note this search is independent of other widgets. Searching supports regex, matching case, and matching entire words. Use `Tab` to toggle between searching by PID and by process name. ### Zoom Using the `+`/`-` keys or the scroll wheel will move adjust the current time intervals of the currently selected widget. Widgets can hold different time intervals independently. ### Maximizing Only care about the CPU widget right now? Then go to the widget and hit `Enter` to make it take up the entire drawing area. ### Config files bottom supports reading from a config file to customize its behaviour and look. By default, bottom will look at `~/.config/bottom/bottom.toml` or `C:\Users\\AppData\Roaming\bottom\bottom.toml` on Unix and Windows systems respectively. Note that if a config file does not exist at either the default location or the passed in location via `-C` or `--config`, one is automatically created with no settings applied. #### Config flags The following options can be set under `[flags]` to achieve the same effect as passing in a flag on runtime. Note that if a flag is given, it will override the config file. These are the following supported flag config values: | Field | Type | |------------------------|---------------------------------------------------------------------------------------| | `avg_cpu` | Boolean | | `dot_marker` | Boolean | | `left_legend` | Boolean | | `current_usage` | Boolean | | `group_processes` | Boolean | | `case_sensitive` | Boolean | | `whole_word` | Boolean | | `regex` | Boolean | | `show_disabled_data` | Boolean | | `basic` | Boolean | | `rate` | Unsigned Int (represents milliseconds) | | `default_time_value` | Unsigned Int (represents milliseconds) | | `time_delta` | Unsigned Int (represents milliseconds) | | `temperature_type` | String (one of ["k", "f", "c", "kelvin", "fahrenheit", "celsius"]) | | `default_widget_type` | String (one of ["cpu", "proc", "net", "temp", "mem", "disk"], same as layout options) | | `default_widget_count` | Unsigned Int (represents which `default_widget_type`) | #### Theming The config file can be used to set custom colours for parts of the application under the `[colors]` object. The following labels are customizable with strings that are hex colours, RGB colours, or specific named colours. Supported named colours are one of the following strings: `Reset, Black, Red, Green, Yellow, Blue, Magenta, Cyan, Gray, DarkGray, LightRed, LightGreen, LightYellow, LightBlue, LightMagenta, LightCyan, White`. | Labels | Details | Example | | ------------------------------- | ---------------------------------------------- | ------------------------------------------------------- | | Table header colours | Colour of table headers | `table_header_color="255, 255, 255"` | | CPU colour per core | Colour of each core. Read in order. | `cpu_core_colors=["#ffffff", "white", "255, 255, 255"]` | | Average CPU colour | The average CPU color | `avg_cpu_color="White"` | | RAM | The colour RAM will use | `ram_color="#ffffff"` | | SWAP | The colour SWAP will use | `swap_color="#ffffff"` | | RX | The colour rx will use | `rx_color="#ffffff"` | | TX | The colour tx will use | `tx_color="#ffffff"` | | Widget title colour | The colour of the label each widget has | `widget_title_color="#ffffff"` | | Border colour | The colour of the border of unselected widgets | `border_color="#ffffff"` | | Selected border colour | The colour of the border of selected widgets | `highlighted_border_color="#ffffff"` | | Text colour | The colour of most text | `text_color="#ffffff"` | | Graph colour | The colour of the lines and text of the graph | `graph_color="#ffffff"` | | Cursor colour | The cursor's colour | `cursor_color="#ffffff"` | | Selected text colour | The colour of text that is selected | `scroll_entry_text_color="#ffffff"` | | Selected text background colour | The background colour of text that is selected | `scroll_entry_bg_color="#ffffff"` | #### Layout bottom supports customizable layouts via the config file. Currently, layouts are controlled by using TOML objects and arrays. For example, given the sample layout: ```toml [[row]] [[row.child]] type="cpu" [[row]] ratio=2 [[row.child]] ratio=4 type="mem" [[row.child]] ratio=3 [[row.child.child]] type="temp" [[row.child.child]] type="disk" ``` This would give a layout that has two rows, with a 1:2 ratio. The first row has only the CPU widget. The second row is split into two columns with a 4:3 ratio. The first column contains the memory widget. The second column is split into two rows with a 1:1 ratio. The first is the temperature widget, the second is the disk widget. This is what the layout would look like when run: ![Sample layout.](assets/sample_layout.png) Each `[[row]]` represents a _row_ in the layout. A row can have any number of `child` values. Each `[[row.child]]` represents either a _column or a widget_. A column can have any number of `child` values as well. Each `[[row.child.child]]` represents a _widget_. A widget is represented by having a `type` field set to a string. The following `type` values are supported: | | | |---------|--------------------------| | `cpu` | CPU chart and legend | | `mem` | Memory chart | | `proc` | Process table and search | | `net` | Network chart and legend | | `temp` | Temperature table | | `disk` | Disk table | | `empty` | An empty space | Each component of the layout accepts a `ratio` value. If this is not set, it defaults to 1. For an example, look at the [default config](./sample_configs/default_config.toml), which contains the default layout. ...and yes, you can have duplicate widgets. This means you could do something like: ```toml [[row]] ratio=1 [[row.child]] type="cpu" [[row.child]] type="cpu" [[row.child]] type="cpu" [[row]] ratio=1 [[row.child]] type="cpu" [[row.child]] type="empty" [[row.child]] type="cpu" [[row]] ratio=1 [[row.child]] type="cpu" [[row.child]] type="cpu" [[row.child]] type="cpu" ``` and get the following CPU donut: ![CPU donut](./assets/cpu_layout.png) ### Compatibility The current compatibility of widgets with operating systems from personal testing: | OS | CPU | Memory | Disks | Temperature | Processes/Search | Networks | | ------- | --- | ------ | ----- | ----------- | ---------------- | -------- | | Linux | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Windows | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | | macOS | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ## Contribution Contribution is always welcome - just submit a PR! Note that I currently develop and test on stable Rust. Thanks to all contributors ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

Marcin Wojnarowski
💻 📦
Mahmoud Al-Qudsi
💻
## Thanks - This project is very much inspired by both [gotop](https://github.com/cjbassi/gotop) and [gtop](https://github.com/aksakalli/gtop). - Basic mode is heavily inspired by [htop's](https://hisham.hm/htop/) design. - This application was written with many, _many_ libraries, and built on the work of many talented people. This application would be impossible without their work.