PPL

A Rust CLI tool for managing and tracking significant dates for the people in your life.

Features

Just enough to get by.

Storage

Shipping a syncable database for the following information

• PPL
  • Contact information
  • Tiers
  • Traits
  • Significant Dates
• Tier Defaults ( Emoji + Color )
• Trait Defaults ( Emoji + Color )
• Reminder Configuration

MOTD

Put a message of the day in your bashrc to remind you of important dates. ppl shell [bash|zsh|fish] adds it to your rc file for you (defaults to $SHELL, --print to just show the snippet).

Dates only show up once they’re inside their tier’s reminder window. Set it with ppl tiers set Family 14 (ppl tiers clear Family to remove, ppl tiers to list), or in the TUI’s tiers tab with enter. ppl motd outputs:

Reminders

By default reminders will only be shown once per day unless otherwise configured. The options are:

• OnlyOnce, // Default, Only the first time the motd is run that day`
• OnceHourly, // Only once per hour, resetting at the top of the hour
• Randomly(u8), // Will show this motd person randomly u8% every run
• Always, // Will always show this person’s upcoming
• Never, // Never show this person’s upcoming

Set the mode per tier with ppl tiers remind Family hourly (daily, hourly, random:30, always, never).

Any of these can be overridden for one person with --person (name, nick or id), e.g. ppl tiers set Family 3 -p Anji, ppl tiers remind Family always -p Anji; ppl tiers clear Family -p Anji goes back to the tier defaults and ppl tiers -p Anji shows what applies.

To see everything the remind modes are hiding, run ppl motd --all: it ignores the modes and dates with reminders off, and doesn’t count as having shown anything, so the next plain ppl motd still reminds as usual. --days 30 looks 30 days ahead for everyone and every calendar instead of their windows, including people in no tier.

ppl motd --rich (with or without --all) prints what each holiday is under it, like the TUI’s i: the blurb and Wikipedia link for built-in holidays, and the location, description and link for iCal events, wrapped to the terminal and cut at four lines.

Notes and todos

Any one occurrence of a date (this year’s Thanksgiving, next Tuesday’s 1:1, Anji’s birthday) can carry notes and todos, which ppl motd --rich prints under it.

ppl notes add thanksgiving bring pie            # the next Thanksgiving
ppl notes add "anji birthday" --todo buy a card # every word has to match
ppl notes add "1:1" -d 2026-11-03 ask about budget
ppl notes                                       # from today on (--all for past ones)
ppl notes done 3                                # tick a todo (again to untick)
ppl notes rm 3

In the TUI, i on any upcoming row (people’s dates too) shows its notes: n adds a note, t a todo, space ticks one, Delete twice removes one. Rows with notes get a 📝, or ☐ and the number of open todos.

In the TUI the same keys work on the tiers tab (defaults) and on a selected tier while editing a person (overrides): m cycles the mode, +/- change the window, [/] change the random %, x clears.

TUI

A Terminal UI for managing all the various stored information in the database.

Default View

PPL List, shows all configured ppl, their tiers, traits and information

Press e to edit the selected person; the 👤 row at the top edits their name and nickname (the nickname is what the list, calendar and motd show). From the CLI: ppl edit Anjali --nick Anji, --name to rename, --nick "" to clear.

Press a to add to the selected person: i tier, r trait, d date, c contact, l relation. While editing a person, Delete (or backspace) twice removes the selected row.

Calendar View

Upcoming anniversaries and holidays for the year; ↑/↓ scroll the upcoming list, which opens on today, and the selected day is highlighted in white in the month grid. Scrolling past the end of the year carries on into the next (and above the start, into the last); PgUp/PgDn jump a year. Like the ppl list’s toggles, n (countries), r (religious), m (moon and fiscal), s (subscribed) and p (people’s dates) show or hide those dates on the calendar tab; hidden ones are struck through in the footer. Press i on a holiday for a short description and a Wikipedia link (o opens it in your browser).

Press c to switch built-in calendars on and off. Their holidays show in the upcoming list and colour the month grid: cyan for countries, violet for religious calendars, amber for moon and fiscal. A country’s states and provinces appear under it once it’s on.

Tier View

Add and Modify Tiers and Defaults. a creates a new tier.

Trait View

Add and Modify Traits and Defaults. a creates a new trait; its kind is trait, date (shows up in the motd and calendar) or contact.

Stats

ppl stats shows a summary of the current database

Tiers & Traits

ppl tiers and ppl traits list all the tiers and traits in the database.

ppl tiers add Neighbors --symbol 🏡 --color teal --days 7   # new tier
ppl tiers add Neighbors -p Anji                             # put someone in a tier
ppl traits add pronouns --symbol 🏳️ --color violet          # new trait
ppl traits add namesday --kind date                         # new kind of date

Colors: red, gold, amber, green, teal, cyan, blue, violet, pink, slate.

Calendars

Built-in holiday calendars, all computed locally (no downloads, any year):

• Countries: United States, Canada, United Kingdom, Ireland, Germany, France, Mexico, Australia, India, Thailand, plus states and provinces for the US, Canada, the UK, Germany and Australia (ppl calendars list --all), and US observances like Mother’s Day and Halloween
• Religious and cultural: Christian (Western and Orthodox), Jewish, Islamic, Chinese (lunar), Persian, Hindu, Buddhist
• Moon and fiscal: moon phases with times and full-moon names, and fiscal quarters for years starting January, April, July or October, plus the retail 4-5-4 calendar

ppl calendars                       # what's on
ppl calendars enable us us-ny jewish lunar
ppl calendars disable jewish
ppl calendars show                  # this year's holidays from the calendars that are on
ppl calendars show hindu -y 2027    # or from any calendar, any year

Turning on a state turns on its country; turning off a country turns off its states.

Subscribed (iCal) calendars

Any iCal calendar can be added alongside the built-in ones: a Google, Outlook or iCloud calendar’s “secret address in iCal format”, a webcal:// link, or a local .ics file.

ppl calendars subscribe work https://calendar.google.com/calendar/ical/.../basic.ics
ppl calendars subscribe family ~/calendars/family.ics
ppl calendars sync                       # fetch now
ppl calendars unsubscribe work

Subscribed calendars are switched on and off, shown, and reminded of like the built-in ones; their group for motd defaults is subscribed (ppl calendars set subscribed 1). Repeating events, moved or cancelled occurrences and multi-day events are handled; timed events show their local start time. Remote calendars are cached in ~/.cache/pplapp/ical and fetched again when they’re 6 hours old, with a 5 second timeout; if that fails (say, offline) the old copy is used. In the TUI, i on an event shows its description, location and link.

Holidays in the motd

ppl motd mentions upcoming holidays from the calendars that are on. Like tiers, each calendar has a window (how many days ahead) and a remind mode (daily, hourly, random:N, always, never), and each group (countries, religious, other for moon and fiscal) has defaults for its calendars. A calendar uses its own setting, then its country’s (for a state), then its group’s, then on the day, daily.

ppl calendars set countries 0            # national holidays on the day
ppl calendars set religious 7            # religious ones a week ahead
ppl calendars remind religious always
ppl calendars set us-ny 3                # but New York's three days ahead
ppl calendars clear us-ny                # back to the defaults

In the TUI’s calendar popup the same keys as the tiers tab work on a calendar or a group heading: +/- days ahead, m mode, [/] random %, x back to the default.

Jewish and Islamic days begin at sundown the evening before. Islamic dates use the Umm al-Qura calendar, and local moon sighting can move them a day. Hindu dates are worked out for India from the positions of the Sun and Moon, and regional calendars can differ by a day. Thailand’s Buddhist days follow the astronomical full moon, so they can be a day off the Thai almanac.