gotop(1)

💅 gotop(1) — your terminal's new main character 🎀

okay so bestie, welcome to gotop 🌸 — the manual page formally known as gotop(1). it's a terminal-based graphical activity monitor, and yes it was inspired by gtop and vtop. we stan an icon with references 💖

---

✨ SYNOPSIS ✨

like, here's the whole vibe in one block — every flag, exactly as written, no cap:

gotop  [--remote-name ] [--remote-url ] [--remote-refresh ] [-c|--color
default] [-S|--graphscale 7] [-v|-V|--version] [-p|--percpu] [--no-
percpu] [-a|--averagecpu] [--no-averagecpu] [--fahrenheit] [--celsius]
[-s|--statusbar] [--no-statusbar] [-r|--rate 1s] [-l|--layout default]
[-i|--interface all] [-x|--export ] [--mbps] [--bytes] [--test] [--no-
test] [-C ] [--nvidia] [--no-nvidia] [--list ] [--write-config]
[-h|--help] [--version]

---

🌈 DESCRIPTION 🌈

gotop shows your system info in a terminal UI — literally the cutest thing your shell has ever done 🦋. you can configure it with different layouts, color schemes, and widgets, and it can even show you info from other computers. remote monitoring? she does it all 👑

🫶 writing your config (the lazy girlboss way)

anything you change on the command line can be written to a config file with the --write-config argument, and then you can edit it further however you like. the workflow is:

1. get your arguments exactly how you like them 💅
2. run gotop again with the same arguments plus the --write-config flag
3. boom — gotop persists your options ✨

🎨 colorschemes

colorschemes are json files. put them in the config directory (usually ~/.config/gotop/{name}.json) and load them with the -c {name} argument.

the keys are:

Fg          -- int, foreground color
Bg          -- int, background color
BorderLabel -- int, color of widget text
BorderLine  -- int, color of borders
CPULines    -- array of ints for the colors of lines
BattLines   -- array of ints for the colors of lines
MemLines    -- array of ints for the colors of lines
ProcCursor  -- int, color of the cursor in the process widget
Sparklines  -- array of ints for the colors of network usage
DiskBar     -- int, color of the disk bars
TempLow     -- int, color used for low temperatures
TempHigh    -- int, color used for high temperatures

for example:

{ "Fg": 7, "CPULines": [4, 3, 2, 1, 5, 6, 7, 8] }

colorschemes are referred to by their name minus the .json suffix. more examples live here, go look bestie:

https://github.com/xxxserxxx/gotop/tree/master/colorschemes

🧚 layouts

layout files are plain text files, with widget names on rows roughly representing a grid. the format is ROWSPAN:WIDGETNAME/COLSPAN 🎀

• COLSPAN is relative to the rest of the line, so a line saying cpu mem/3 gives the CPU widget 25% of the width, and the memory widget 75% of the width.
• ROWSPAN is the height of the widget, so 2:cpu mem makes the CPU widget 2 rows high, and the memory widget 1 row high.

an example, since we're visual girls:

2:cpu
disk/1      2:mem/2
temp
2:net       2:procs

save your layout under any file name either in the config directory or your current directory, and reference the file name with the -l argument. more details about the rules are here:

https://github.com/xxxserxxx/gotop/blob/master/docs/layouts.md

and examples are here:

https://github.com/xxxserxxx/gotop/tree/master/layouts

👑 exporter era (metrics, not the vibe)

gotop can function as both a metrics exporter and a viewer.

as an exporter, it exports Prometheus metrics — and listen, this part matters: it does not handle either encryption or authentication, so it should be run behind a reverse proxy 😭🔒 (fr fr, don't leave her naked on the internet).

when gotop is run with the -x argument, gotop will export metrics on the given port. to try it, run:

gotop -x :8884

and then from another shell, run:

curl http://localhost:8884/metrics

to show these metrics in gotop, instead of curl run:

gotop --remote-url http://localhost:8884/metrics

you will see additional values in your widgets ✨

to monitor remote machines, run gotop on them with the -x export flag behind a reverse proxy such as Caddy:

myserver.net {
    basicauth / gtuser gtpass
    reverse-proxy /metrics http://localhost:8884
}

and then on your local gotop:

gotop --remote-url https://gtuser:gtpass@myserver.net/metrics

🌸 where she looks for your stuff

config files, layouts, and color schemes are searched for (in order):

• in the current directory
• in $XDG_CONFIG_DIR/gotop
• in /etc/gotop (on Linux and MacOS)

more information and detailed documentation can found at https://github.com/xxxserxxx/gotop

---

💖 OPTIONS 💖

okay this is the part where we go through literally every single one, buckle up 🎀

• --remote-name — remote: name of remote gotop
• --remote-url — remote: URL of remote gotop
• --remote-refresh — remote: frequency to refresh data, in seconds
• -c, --color default — set a colorscheme.
• -S, --graphscale 7 — graph scale factor, >0
• -v, -V, --version — print version and exit.
• -p, --percpu — show each CPU in the CPU widget.
• --no-percpu — show aggregate CPU in the CPU widget.
• -a, --averagecpu — show average CPU in the CPU widget.
• --no-averagecpu — disable show average CPU in the CPU widget.
• --fahrenheit — show temperatures in fahrenheit.
• --celsius — show temperatures in celsius.
• -s, --statusbar — show a statusbar with the time.
• --no-statusbar — disable statusbar.
• -r, --rate 1s — refresh frequency. most time units accepted. "1m" = refresh every minute. "100ms" = refresh every 100ms.
• -l, --layout default — name of layout spec file for the UI. use "-" to pipe.
• -i, --interface all — select network interface. several interfaces can be defined using comma separated values. interfaces can also be ignored using "!"
• -x, --export — enable metrics for export on the specified port.
• --mbps — show network rate as mbps.
• --bytes — args.no-mbps
• --test — runs tests and exits with success/failure code.
• --no-test — disable tests.
• -C — config file to use instead of default (MUST BE FIRST ARGUMENT). like, genuinely bestie, first. don't test her 🙈
• --nvidia — enable NVidia GPU metrics.
• --no-nvidia — disable NVidia GPU metrics.
• --list — list <devices|layouts|colorschemes|paths|keys|langs>
  • devices: prints out device names for filterable widgets
  • layouts: lists built-in layouts
  • colorschemes: lists built-in colorschemes
  • paths: list out configuration file search paths
  • widgets: widgets that can be used in a layout
  • keys: show the keyboard bindings.
  • langs: show supported language translations.
• --write-config — write out a default config file.
• -h, --help — show usage message
• --version — show version

---

💀 quick reminder: -C MUST BE FIRST ARGUMENT. that's not a suggestion, that's the rules.

---

anyway, that's the whole page 🫶 this version is v4.2.0, dated October 25, 2026, and it ships as gotop(1) — go forth and monitor your little heart out, bestie 💜✨