Settings and config file

The settings page#

s (or Settings in the plottypus ≡ menu) opens settings. It replaces the dashboard entirely rather than floating over it; sampling carries on underneath.

text

 plottypus › settings                                                     esc close

 ▌ general   │ ▌ sample every    ‹ 500 ms ›
   appearance│   layout            auto
   panels    │   network units     bytes/s
   processes │   battery saver     auto
   keys      │   preset            custom
   about     │

               How often plottypus samples. Faster is smoother; slower uses less power.

 ↑↓ move  ←→ change  tab section  / search  esc close

↑ ↓ or j k move; ← →, h l, enter or space change the value; tab switches section.
/ searches every section by name or description. esc clears the search; a second esc closes.
Click a section, click a value to cycle it, scroll to move.
appearance previews every theme with its own colours; click one to use it. about shows the version, the config path and your licence tier.

Changes apply at once and are saved a second later.

Where the file lives#

text

$XDG_CONFIG_HOME/plottypus/config.toml
~/.config/plottypus/config.toml          # when XDG_CONFIG_HOME is not set

--config <path> reads a different file for one run. The file does not exist until you change something.

How it is saved#

Only when you change something, one second after the last change, and again on quit or on HUP, TERM or INT.
Only the keys you changed. Your comments, your ordering and keys plottypus does not know are left exactly as they were.
Atomically: a temporary file, then a rename, so a crash never leaves half a file. If config.toml is a symlink (a dotfiles repo, say), the write goes to its target and the link survives.
A read-only file is never written. The footer says config is read-only (not saved) once and the session carries on.
A file that does not parse is copied to config.toml.bak, left alone, and the session runs on defaults.
A value of the wrong type or out of range falls back to its default on its own and is named in the footer; the rest of the file still applies.

Every key#

The defaults, as a complete file:

toml

version = 1
interval_ms = 500        # 250, 500, 1000, 2000 or 5000
surface = "auto"         # auto | work | glance
theme = "auto"           # auto or a theme name
icons = "auto"           # auto | unicode | nerd | none
keymap = "default"       # default (same as plottypus) | htop | btop
low_power = "auto"       # auto | on | off
zen = false              # hide the footer and the scale labels
glass = "auto"           # auto | on | off: clear backgrounds for see-through windows
extra_contrast = false

[panels]
gpu = true
net = true
disk = false
fans = true              # the heat box: fans and temperatures
power = true             # battery, or system watts on a desktop
cores = true             # per-core bars in the cpu box

[proc]
tree = false
threads = false          # add a thread-count column
ratio = 55               # process pane width, % (35 to 72); dragging the split saves it
cpu_unit = "core"        # core (100% = one core) | total (100% = the whole chip)

[proc.sort]
column = "cpu"           # cpu | mem | pid | name | user | state | gpu | rss | threads
                         # | power | read | write | wakeups | started
desc = true              # biggest first

[units]
net_bits = false         # true: network in bits/s instead of bytes/s

Key	Settings page	What it does
`interval_ms`	general → sample every	How often plottypus samples. `[` and `]` step it live.
`surface`	general → layout	`work` or `glance` at start; `auto` picks by window size.
`units.net_bits`	general → network units	Bytes per second (like Finder) or bits per second (like your ISP).
`low_power`	general → battery saver	Saved, but has no effect in 1.0.0: sampling does not slow down on battery yet.
—	general → preset	Applies one of the five presets; `custom` when your settings match none.
`theme`	appearance → theme	See Themes and glass.
`icons`	appearance → icons	Glyphs beside each box title. `nerd` needs a Nerd Font; `none` is plain ASCII.
`glass`	appearance → glass	For translucent windows: no cell backgrounds, brighter frames.
`extra_contrast`	appearance → extra contrast	Brighter dim text, hints and frames over a busy wallpaper.
`zen`	appearance → zen mode	Graphs only. `Z` toggles it.
`panels.*`	panels	Show or hide each box. A box for hardware your Mac lacks stays hidden either way.
`proc.sort.column`, `proc.sort.desc`	processes → sort by, biggest first	The process order. Clicking a header does the same.
`proc.tree`	processes → tree view	Nest each process under its parent.
`proc.threads`	processes → threads column	Add a thread-count column.
`proc.cpu_unit`	processes → cpu percent	`core`: 100% is one core. `total`: 100% is the whole chip.
`proc.ratio`	processes → list width	Process pane width in percent, in steps of 5.
`keymap`	keys → key profile	`plottypus`, `htop` or `btop`. See Keys.

-i on the command line accepts anything from 100 ms to 60 s (250, 250ms, 1s, 1.5s) for that run. The config file and the settings page stick to the five steps above. Command-line flags (-i, --theme, --surface) apply to that run only; saving other changes does not write them into the file.

Environment variables#

These win over the file.

Variable	Effect
`PLOTTYPUS_THEME=<name>`	Use that theme. `auto` reads the terminal.
`PLOTTYPUS_ICONS=nerd`	Nerd Font icons in panel titles (`none` for plain ASCII).
`PLOTTYPUS_KEYS=htop`	Key profile: `plottypus`, `htop` or `btop`.
`PLOTTYPUS_GLASS=on`	Glass: `on`, `off`, `auto`, or an opacity such as `0.8`.
`PLOTTYPUS_COLORS=256`	Force colour depth: `truecolor`, `256`, `16` or `none`.
`NO_COLOR=1`	Monotreme with attributes only. A `PLOTTYPUS_THEME` name overrides it.
`XDG_CONFIG_HOME`	Where `plottypus/config.toml` and `license.toml` live.

Old config files#

Files from before v1 (flat keys like show_gpu, sort, proc_ratio) still load unchanged. Each old key is moved to its v1 name the first time you change that setting, one key at a time, so nothing is rewritten behind your back.

plottypus --print-config prints the effective preferences after flags and exits. In 1.0.0 it prints a short summary using those older flat names (interval_ms, surface, theme, mouse, show_gpu, show_net, show_disk, show_fans, show_cores, show_threads, show_tree, sort, proc_ratio), not the full v1 file above. Anything plottypus writes to config.toml uses the v1 names.