Basic usage¶

Launching¶

rainlog           # launch the TUI
rainlog tui       # same
rainlog --help    # list options
rainlog --version # print version

Layout¶

The TUI has two panels side by side:

Chart (left): Vertical bar chart, auto-scaled to the terminal width.
Stats (right): Current mode, grouping, period totals/averages, and current streak.
Footer: Active key bindings for the current context.

Chart modes¶

Press m to cycle through:

Mode	What is shown
Rainfall	Raw daily totals in mm
Soil-moisture index	Exponentially decaying moving sum — a proxy for ground saturation
Comparison	Year-over-year comparison (monthly and yearly groupings only)

Comparison mode¶

Comparison mode is available when the grouping is monthly or yearly; pressing m skips it in daily and weekly groupings.

Yearly grouping: one bar per year, each showing the Jan 1 → today total (same calendar window across all years so they are directly comparable).
Monthly grouping: grouped bars, one cluster per month with one bar per year side by side.

In comparison mode + / - adjust how many prior years are shown instead of the bar count. Scroll, bar-select, and edit are disabled while in comparison mode.

Grouping¶

Press g to cycle through:

Grouping	Bar represents
Daily	One calendar day
Weekly	One ISO week
Monthly	One calendar month
Yearly	One calendar year

Scrolling¶

Use ← / → to scroll back and forward through history. The most-recent period is always on the right.

Bar count¶

Key	Effect
`+`	Add one bar (switches to manual mode)
`-`	Remove one bar (switches to manual mode)
`a`	Reset to auto (fills available terminal width)

Tentative entries¶

Days since the last logged record are shown as amber bars: 0 mm in rainfall mode, decayed moisture estimate in soil-moisture mode. They become permanent bars once a record is logged.

Adding a record¶

Press n to open the Add Rain modal:

Field	Description
Date	Target day in YYYY-MM-DD format (defaults to today)
Amount	Rain total in mm (non-negative)
Back-fill zeros	On by default. Inserts 0 mm for every day between the previous record and this one, keeping the database complete. Turn off only if you intentionally want to leave a gap.

Press Ctrl+S to save or Escape to cancel.

Editing a record¶

Press e to open the Edit Rain modal. In daily grouping:

Press s to enter bar-select mode.
Use ← / → to highlight the bar to correct.
Press e — the modal pre-fills the date and amount from the selected bar.

Press Ctrl+S to save or Escape to cancel.

Database directory¶

rainlog --db-dir ~/weather-data

The database file is always named rainlog.sqlite inside the given directory.