Skip to content

configuration.md

Latest commit

 

History

History
189 lines (141 loc) · 4.54 KB

configuration.md

File metadata and controls

189 lines (141 loc) · 4.54 KB
Raw

Configuration

toolstash stores user data under $XDG_CONFIG_HOME/toolstash when XDG_CONFIG_HOME is set, otherwise under ~/.config/toolstash.

The app creates and updates files as you use it. You do not need to create a config file by hand.

Files

file purpose
config persisted settings
notes scratchpad notes
timelog time log rows
board board cards
api HTTP collections
db database connections
fsm state machines
erd database schemas
uml UML diagrams (experimental)
themes/*.toml custom themes

Main Config

config is a simple key = value file. Unknown keys are ignored, so a config from a newer version can still load in an older one.

Example:

theme = nord
nerd = true
images = true
backend = tui
wrap = true
topline = cpu:left,mem:left,clock:right
statuses = todo,doing,done
dashboard = regex,calc,notes,time,uml

Persisted settings:

  • theme: selected theme name.
  • nerd: whether to use Nerd Font glyphs.
  • images: whether gp shows a diagram as a picture on a terminal that speaks the kitty graphics protocol.
  • backend: who draws an exported diagram — tui, graphviz, tikz, plantuml or mermaid.
  • wrap: whether notes wrap long lines.
  • topline: status-row segments and where they are placed.
  • statuses: board columns, in order.
  • dashboard: enabled dashboard tools, in display order.

Some settings are intentionally session-only:

  • Regex flags: ignore case, multi-line anchors, dot-all.
  • Calculator display: base, word size, signed/unsigned.

Those settings belong to the question currently being answered, so a fresh run starts from defaults.

Settings Panel

Press s to open settings. The panel has tabs for general app settings, dashboard tiles, topline placement, and tools that expose settings.

General settings:

  • theme
  • nerd font icons
  • diagram images
  • diagram backend

Dashboard settings:

  • Every tool has one row.
  • Enter, Space, or the right arrow toggles a tool on or off.
  • J and K move an enabled tool down or up in dashboard order.
  • At least one tool must stay enabled.
  • The order is also the numbering used by 1gt, 2gt, and the tile labels.

Topline settings:

  • user and host
  • uptime
  • load average
  • CPU use
  • memory use
  • battery
  • date
  • clock

Each topline segment can be off, left, or right. Press Enter to cycle forward and the left arrow to cycle backward. Segments on each side keep the same built-in order regardless of the order in the config file.

If every segment is off, the top row disappears and the app gives that height back to the tool.

Dashboard

The default dashboard shows every tool in the built-in order. Once customized, the config stores the enabled tool names:

dashboard = calc,regex,uml

An empty or missing dashboard row means "show every tool". Unknown names are ignored, so a config copied from another install does not stop the app from opening. If all names are unknown, toolstash falls back to the built-in dashboard.

Topline

The default top row shows CPU and memory on the left and the clock on the right:

topline = cpu:left,mem:left,clock:right

A bare segment name is treated as right for compatibility with older config files:

topline = mem,clock:left

Everything displayed in the top row is read from files or calculated in-process once a second. At startup, toolstash runs date +%z once to find the local time zone.

Themes

Built-in themes:

  • tokyonight
  • catppuccin
  • monokai
  • gruvbox
  • nord
  • dracula

Cycle themes with t and T. Persist the selected theme through settings, or launch one run with:

toolstash --theme nord

Add custom themes under:

~/.config/toolstash/themes/

Each theme file is named <theme>.toml and contains key = "#rrggbb" lines:

accent = "#7aa2f7"
ok = "#9ece6a"
err = "#f7768e"
muted = "#565f89"
selected = "#292e42"
bg = "#1a1b26"
panel = "#16161e"
fg = "#c0caf5"

Unknown keys and invalid colors are ignored. A custom theme file with the same name as a built-in theme replaces the built-in one.

Tool Data

The persistent tool files are designed to be understandable from a terminal. They are not an API contract, but they are deliberately simple enough to back up, diff, grep, or repair manually.

The time log is the most human-facing format:

2026-08-04 09:00-10:30 the parser
2026-08-04 10:30-11:15 review
2026-08-04 11:15-       still going

A line that cannot be parsed is skipped rather than causing data loss.