RemindMail: Reminder Management Tool

A powerful CLI designed to help you schedule and organize reminders efficiently and effectively. Easily manage your To Do list, schedule one-time or recurring reminders, add notes, and view and manage upcoming reminders, all from the comfort of your terminal.

RemindMail: Reminder Management Tool
- Table of Contents
✨ New in 3.0.0:
Features
Dependencies
Installation and Setup
Usage
- Scheduling Reminders With TUI
  - VI Mode and Keybindings
- Scheduling Reminders With remindmail.yml
  - YAML Key Reference
    - name
    - every
    - unit
    - offset
    - day
    - dom
    - date
    - later
    - delete
    - notes
    - command
    - email
    - tags
  - Good Examples
Contributing
License
Disclaimer
Author Info

✨ New in 3.0.0:

Migrated from a custom .md file to a YAML file
- Allows for easier extensibility in future releases
Added optional tags for more flexible scheduling
Better handling for errors and edge case
Improved TUI for delete and command options

Features

RemindMail offers a variety of features to enhance your productivity:

Easily manage your To Do list from anywhere in the terminal
Send one-time or recurring reminders to your inbox
Add notes or "for later" reminders
View and manage upcoming reminders
Organize reminders with tags for better filtering

Dependencies

zsh or bash
python3
cabinet
- used to store the remindmail.yml path and other important variables
a configured SMTP server (many email providers offer this, but Gmail will not work)

Installation and Setup

Full Install (recommended)

  pip install remindmail

  # adjust path accordingly
  pip install -r requirements.md

  cabinet --configure # see below for instructions

Minimal Install (experimental)

curl -s https://api.github.com/repos/tylerjwoodfin/remindmail/releases/latest \
| grep "browser_download_url" \
| cut -d '"' -f 4 \
| xargs curl -L -o remindmail.pex

sudo mv remindmail.pex /usr/local/bin/remind

remind -m cabinet --config

Cabinet Configuration

cabinet is installed as a dependency.
initialize using cabinet --configure; see cabinet's README for details.
add the properties below using cabinet -e:

{
  "remindmail": {
    "mongodb_enabled": true, # optional if using mongodb - default false
    "subject_prefix": "Reminder ", # optional - custom prefix for email subjects (default: "📌 ")
    "update-checks": true, # optional - email once per new release during --generate (default: true)
    "path": {
        "file": "/path/to/remindmail.yml"
    }
  },
  "email": {
      "from": "YourUniqueAndNonGmailEmailAddress",
      "from_pw": "YourPassword",
      "from_name": "Your Name",
      "to": "RemindersSentToThisEmailAddress",
      "smtp_server": "your domain's smtp server",
      "imap_server": "your domain's imap server",
      "port": 465
  }
}

Gmail will not work due to their security restrictions.
it's very bad practice to store your password in plaintext; take appropriate precautions.
When update-checks is true (the default), remind --generate checks PyPI for a newer RemindMail version. If one is available, you get a single email per release (subject like 🎉 RemindMail 4.0.0 Released) with upgrade instructions. Set "update-checks": false to disable. RemindMail stores last_notified_version automatically so each version is only emailed once.

MongoDB Configuration

MongoDB is used to log reminders when mongodb_enabled is set to true.
This is configured via the Cabinet configuration in ~/.config/cabinet/config.json - see https://www.github.com/tyjerwoodfin/cabinet for configuration instructions.

Scheduling Reminder Emails

type "crontab -e" in the terminal and add something like:
- 0 4 * * * remind --generate (sends untagged reminders for today at 4AM; use --tags blah to send reminders tagged with 'blah')
- 0 4 * * * remind --later (sends emails scheduled for later)
your setup may require remind to be replaced with something like:
- 0 4 * * * python3 /path/to/site-packages/remind/remind.py --generate
this function requires use of SMTP through Cabinet; please ensure you've configured this correctly.

Usage

remind: Schedule a new reminder interactively
remind --title 'reminder title' --when 'june 20': Schedule a new reminder programatically
remind --title 'reminder title' --when '2024-06-20': Schedule a new reminder programatically
remind --title 'reminder title' --when 'every 3 weeks': Schedule a new reminder programatically
remind --title 'reminder title' --when 'friday': Schedule a new reminder programatically
remind --title 'reminder title' --when friday --save: Schedule a new reminder programatically, saves without confirmation
remind --title 'reminder title' --when 'every 2 Mondays': Schedule a new reminder programatically
remind --title 'Donate to Wikipedia' --when 'every december 1': Schedule an annual reminder (stored as MM-DD)
remind --title 'reminder title' --when 'now': Sends an email immediately
remind -h (or --help): Displays usage information.
remind -g (or --generate): Generates reminders scheduled for today.
- Without --tags: only sends reminders that have no tags (untagged reminders).
- With --tags tag1,tag2: only sends reminders that have at least one of the specified tags.
- With --tags __ALL__: sends all reminders for today regardless of tags (failsafe; not recommended for regular use).
- Use --dry-run to see what would be sent without actually sending anything.
- Also checks PyPI for a newer RemindMail release and emails once per version when remindmail → update-checks is enabled (default).
- remind -g --file=/path/to/special/remindmail.yml will use the specified file instead of the default.
- I recommend setting up a crontab.
remind --later: Emails reminders that are marked with [later]
remind --st (or --show-tomorrow): Lists reminders in remindmail.yml that target tomorrow's date
remind --sw (or --show-week): Lists reminders for the next 7 days
remind -e (or --edit): Opens remindmail.yml in your configured editor
remind --list-all: Lists all reminders in remindmail.yml. Useful for debugging.
remind --find 'search text': Displays reminders containing the given text in title, date, or day fields.
- Text search examples: remind --find laundry, remind --find monday
- Date search examples: remind --find 2025-04-24, remind --find 04/24
- If search text is a valid date, displays reminders that would send on that date.
cabinet --config: Configures cabinet

Scheduling Reminders With TUI

unless --save is used, a confirmation will appear.
use arrow keys (or j and k in VI Mode) to navigate.
arrow left and right to iterate through:
- type
- value
- frequency
- starting date ("Starts On")
- offset

VI Mode and Keybindings

when the confirmation appears, use j or k to enter VI mode.
j and k navigate up and down; h and l navigate left and right.
use i to exit VI mode.
use q to cancel the reminder.

Scheduling Reminders With remindmail.yml

The remindmail.yml file is a YAML configuration file that contains your reminders.
Each reminder is defined as an object under the reminders key.

YAML Key Reference

`name`

Type: string
Description: The description or title of the reminder.

`every`

Type: int
Description: How often the reminder recurs (e.g. every 2 units of time).
Default unit: days (unless unit is specified).

`unit`

Type: string (days, weeks, months)
Description: Time unit for every. Only needed for non-day intervals.

`offset`

Type: int
Description: Delay (in same units as every) before the first occurrence.

`day`

Type: string (mon, tue, ..., sun)
Description: Specifies a day of the week for weekly reminders.

`dom`

Type: int (1–31)
Description: Day of the month when the reminder occurs.

`date`

Type: string (YYYY-MM-DD or MM-DD)
Description: A specific one-time (YYYY-MM-DD) or annual (MM-DD) date for the reminder.
CLI: every december 1 (and month-name variants) creates an annual MM-DD reminder.

`later`

Type: bool
Description: Marks the reminder as unscheduled or saved for later.

`delete`

Type: bool
Description: If true, the reminder should be deleted after it's triggered.

`notes`

Type: string
Description: If set, sends within the body of the email and marks the subject with 📝. Basic HTML is supported.

`command`

Type: string
Description: If set, runs the command and outputs the results to the body of the email.

`email`

Type: string
Description: Optional email address to send this specific reminder to. If not set, uses the default email configured in Cabinet's email -> to setting.

`tags`

Optional list of tags to categorize and filter reminders. Tags can be used to group related reminders and filter which reminders are sent when using the --generate command.

Tag filtering when generating:

No --tags: Only reminders with no tags are sent. Use this for your default morning cron so that tagged reminders (e.g., evening) are held for their dedicated runs.
--tags tag1,tag2: Only reminders that have at least one of the specified tags are sent.
--tags __ALL__: Sends all reminders for today regardless of tags. Use as a failsafe only, not for regular use.

Example crontab setup for morning and evening runs:

0 4 * * * remind --generate                    # Morning: sends untagged reminders only
0 18 * * * remind --generate --tags evening    # Evening: sends reminders tagged "evening"

Example:

reminders:
  - name: "Weekly team meeting"
    day: "mon"
    tags: ["work", "meeting"]
    notes: "Don't forget to prepare the agenda"
    
  - name: "Grocery shopping"
    every: 7
    tags: ["personal", "shopping"]
    notes: "Buy milk and eggs"

You can filter reminders by tags when generating:

remind --generate --tags work,meeting   # Only sends reminders with work or meeting tags
remind --generate --tags evening        # Only sends reminders with evening tag
remind --generate                       # Only sends reminders with no tags (default)
remind --generate --tags __ALL__        # Sends all reminders for today regardless of tags (failsafe)

Tags can be specified by a string or list in the YAML file:

tags: "meeting"

tags: ["work", "meeting"]

Good Examples

Here are some examples of how your remindmail.yml file could look:

reminders:
  - name: Workout and Stretch
    day: mon,wed,fri
    delete: false
  - name: Try Cursor IDE
    date: 2025-03-31
    delete: true
    notes: This will be <u>VERY</u> useful! <b>WOW</b>
  - name: Donate to Wikipedia
    date: 12-01
  - name: Laundry and Sheets
    every: 6
    offset: 5
    delete: false
  - name: Monthly Budget
    unit: months
  - name: Change Toothbrush Head
    every: 3
    unit: months
    offset: 2
    delete: false
  - name: Try Umbrell OS
    later: true
  - name: Update Team Spreadsheet
    day: wed
    every: 2
    offset: 1
  - name: Homework File Count
    day: fri
    command: find ~/homework -maxdepth 1 -type f | wc -l
    notes: This is how many files are in ~/homework.
  - name: Send to spouse
    date: 2025-11-15
    email: spouse@protonmail.com
    notes: This reminder will be sent to a different email address

⚠️ Comments and extraneous spacing will NOT be saved after reminders are generated.

Contributing

Contributions to RemindMail are welcome! Please feel free to fork the repository, make your changes, and submit a pull request.

License

RemindMail is released under the MIT license. For more details, see the LICENSE file in the repository.

Disclaimer

This is a non-commercial, open-source project; your data is your responsibility. Take appropriate precautions to shield sensitive information.
I cannot be held responsible for any data loss or other issues that may arise from using this tool.

Author Info

Metadata

Release files for remindmail 1!3.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for remindmail 1!3.5.1
File	Size	Uploaded
remindmail-1!3.5.1.tar.gz	42.4 kB	Sep 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for remindmail 1!3.5.1
File	Interpreter	ABI	Platform	Reset
remindmail-1!3.5.1-py3-none-any.whl 37.1 kB Sep 30, 2026	Python 3	none	any	Details

Total release size: 79.5 kB

Release files / remindmail-1!3.5.1.tar.gz

Download URL	remindmail-1!3.5.1.tar.gz
Size	42.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`0eabf1c91eedb8fad3dbc92549f7581cca6ea94dd6ef65b7df9849ead27d2679`
BLAKE2b-256 checksum How to use checksums	`f63b8980db400dcf3482a561591e5a0429659a0d438a28e75fce00d066b3896c`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`

Release files / remindmail-1!3.5.1-py3-none-any.whl

Download URL	remindmail-1!3.5.1-py3-none-any.whl
Size	37.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3a2c69f631b81b4930af8eeea63aa5e6c2d14b173d7421d8a3ebb1b7befcb067`
BLAKE2b-256 checksum How to use checksums	`fe7ee761682621212680a8b44d2fb7b8789d1a2ff3ffaceee1e34c14bed75e8e`
Upload date	Sep 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`