/hey.py

Dead simple reminder CLI tool for linux; Reminders are shown on Web and Mobile using your own Telegram bot

Primary LanguagePython

Hey - your personal telegram notifier

Set simple one-shot reminders and texts with an easy, approachable CLI with notifications on all your devices

Why

  1. Dead simple - all of 130 lines in a single script file

  2. No server process to run. Uses atd daemon and most likely that’s already running

  3. Telegram clients are available for pretty much every platform

  4. Handles fuzzy, human friendly dates and times (like friday after next); Handles timezone conversions as well (so 9AM EST)

    But my machine isn’t ONLINE 24x7

  5. Install it on a server and with password-less ssh and setup a shell script or alias to execute hey on the server.

Installation

# clone the repo
# cd into the folder

./install.sh

# check if at daemon is enabled & running
sudo systemctl status atd

# Enable and start it if needed.
sudo systemctl enable atd
sudo systemctl start atd

That’s about it for installation You’ll need to configure a telegram bot before you can get started. See the section below

Configuration

Create a telegram BOT

  1. Create a telegram bot and send it a message

    • search for BotFather

    • type /newbot

    • give it a friendly name and a bot name (bot name must end in _bot)

    • Pick up the bot token from botfather.

  2. Get a chat id

    • Telegram global search, type your bot name or id

    • type /start

    • send any text.

    • Run curl https://api.telegram.org/bot$TOKEN/getUpdates

          {
  "ok": true,
  "result": [
    {
      "update_id": 519260759,
      "message": {
        "message_id": 2,
        "from": {
          "id": 535955002,
          "is_bot": false,
        },
        "chat": {
          "id": 123456789, //(1)
          "type": "private"
        },
        "date": 1567922393,
        "text": "hello"
      }
    }
  ]
}

  3. Update the config file in the folder with the bot token and chat id

Timezone

In case you run this on a server that’s on UTC (As with most cloud providers), then set the TIMEZONE=<Tz code> to set the timezone of the client machine.

NOTE Once again, this isn’t the server timezone. If your client and server are in the same timezone, then DO NOT specify the timezone (key should not present)

NOTE 2: Timezone code is one of TZ database names, like so - TIMEZONE=Asia/Kolkata see TZ Database

Config file locations

Files are read in the following sequence, later files override earlier entries defined in earlier ones. . Alongside hey.py, named as config . /etc/hey.conf . ~/.config/hey.conf

Usage

> hey.py /t 10 AM Friday /m Get a hair cut


# My local timezone is India (IST, +0530), hey is on a server on UTC
# and you can have tz info in the string - say some office opens at 9 AM EST

> hey.py -t 9 AM EST -m call customer support
reminder 'call customer support' set for 10:30 PM 2019-10-16
Note
 arg parsing is basic and does not follow typical shell parsing conventions. First arg has to be /t and then it scans forward till a /m. The gathered string is parsed to a date. Anything after the /m is just concatenated to the message.

Time expressions

Time expression examples:
    in 10 minutes
    in 1 month
    next week
    friday 10 AM
    wed 10 AM
    10 AM Tues
Refer to https://dateparser.readthedocs.io/en/latest/ for documentation on date
expressions