remind - CLI Reminder Tool

A command-line utility for managing quick reminders, featuring natural language processing (using OpenAI) and desktop notifications on Linux.

Requirements

• Node.js: Version 18 or higher (with ESM support).
• libnotify-bin: For receiving desktop notifications. Install it with:

  sudo apt-get update && sudo apt-get install -y libnotify-bin

Configuration

Environment Variables

The system is configured via environment variables. Export them in your ~/.bashrc, ~/.zshrc, or similar.

# (Optional) OpenAI API Key for natural language processing
export OPENAI_API_KEY="sk-XXXXX..."

# (Optional) OpenAI model to use
export OPENAI_MODEL="gpt-4o-mini"

# (Optional) Your default IANA timezone
export REMIND_TZ="Europe/Madrid"

If OPENAI_API_KEY is not set, the tool will operate in a fallback mode, creating reminders 10 minutes in the future without smart processing.

Installation

To install the remind and remind-check commands on your system, use npm link.

cd ~/.remind-js
npm link

This will create symbolic links in your Node binaries directory, making the commands globally accessible.

Usage

Creating a Reminder

Use the remind command followed by a phrase in natural language.

remind "remind me to call Borja tomorrow at 9:30 AM"
remind "notify me in 25 minutes to take out the bread"
remind "team meeting next Monday at 4pm"

The system will respond with the JSON object of the created reminder and save it to ~/.remind/tasks.jsonl.

Listing Pending Reminders

To see a list of all reminders that have not yet been notified, use the list command.

remind list

This will display a formatted list ordered by date:

--- Pending Reminders ---
- Notification test (For: Saturday, August 23, 2025, 1:31 PM)
- Call Borja (For: Wednesday, August 27, 2025, 9:30 AM)

For a more detailed output in JSON format, ideal for scripting or debugging, add the --debug flag:

remind list --debug

Checking Reminders

The remind-check command runs automatically in the background (via systemd or cron) to send notifications. You do not need to run it manually.

Scheduling

For notifications to work, remind-check must be executed periodically. Using systemd is recommended.

Option 1: systemd (Recommended)

Two user unit files will be created:

• ~/.config/systemd/user/remind-check.service
• ~/.config/systemd/user/remind-check.timer

To activate the service to run every minute:

systemctl --user daemon-reload
systemctl --user enable --now remind-check.timer

To check its status:

systemctl --user status remind-check.timer

Option 2: cron (Alternative)

If you prefer to use cron, you can add the following line to your crontab:

# Open the crontab editor
crontab -e

And add this line, which runs the check every minute:

* * * * * DISPLAY=:0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u)/bus XDG_RUNTIME_DIR=/run/user/$(id -u) ~/.remind-js/bin/remind-check >/dev/null 2>&1

Note: The path to remind-check may vary. Ensure it is correct. The environment variable prefix is necessary for notify-send to work from cron.

Utilities (with jq)

Reminders are stored in ~/.remind/tasks.jsonl. You can use jq to inspect them.

View pending reminders:

jq -c 'select(.notified==false)' ~/.remind/tasks.jsonl

Clear notified reminders:

jq -c 'select(.notified==false)' ~/.remind/tasks.jsonl > ~/.remind/tmp && mv ~/.remind/tmp ~/.remind/tasks.jsonl