kha7iq / pingme

PingMe is a CLI which provides the ability to send messages or alerts to multiple messaging platforms & email.

PingMe CLI

Documentation • Supported Services • Install • Github Action • Configuration • Contributing •

---

About

PingMe is a personal project to satisfy my needs of having alerts, most major platforms have integration to send alerts but its not always useful, either you are stuck with one particular platform, or you have to do alot of integrations. I needed a small utility which i can just call from my backup scripts, cron jobs, CI/CD pipelines or from anywhere to send a message with particular information. And i can ship it everywhere with ease. Hence, the birth of PingMe.

Everything is configurable via environment variables, and you can simply export the logs or messages to a variable which will be sent as message, and most of all this serves as a swiss army knife sort of tool which supports multiple platforms.

Supported services

• Discord
• Email
• Gotify
• Line
• Mastodon
• Mattermost
• Microsoft Teams
• Pushbullet
• Pushover
• RocketChat
• Slack
• Telegram
• Textmagic
• Twillio
• Zulip
• Wechat

Install

MacOS & Linux Homebrew

brew install kha7iq/tap/pingme

Shell Script

By default pingme is going to be installed at /usr/bin/ sudo is requried for this operation.

If you would like to provide a custom install path you can do so as input to script. i.e ./install.sh $HOME/bin

curl -s https://raw.githubusercontent.com/kha7iq/pingme/master/install.sh | sudo sh

or

curl -sL https://bit.ly/installpm | sudo sh

Linux

• AUR

# build from sources
yay -S pingme

# binary
yay -S pingme-bin

Manual

# Chose desired version, architecture & target os
export PINGME_VERSION="0.2.6"
export ARCH="x86_64"
export OS="Linux"
wget -q https://github.com/kha7iq/pingme/releases/download/v${PINGME_VERSION}/pingme_${OS}_${ARCH}.tar.gz && \
tar -xf pingme_${OS}_${ARCH}.tar.gz && \
chmod +x pingme && \
sudo mv pingme /usr/local/bin/pingme

Windows

scoop bucket add pingme https://github.com/kha7iq/scoop-bucket.git
scoop install pingme

Alternatively you can head over to release pages and download deb, rpm or binary for windows & all other supported platforms.

Docker

Docker container is also available on both dockerhub and github container registry.

latest tag will always pull the latest version available, or you can also download specific version. Checkout release page for available versions.

Docker Registry

docker pull khaliq/pingme:latest

Github Registry

docker pull ghcr.io/kha7iq/pingme:latest

Run

docker run ghcr.io/kha7iq/pingme:latest

Github Action

A github action is available for integration with your workflows, you can find it on Github Market Place or here Github Repo.

- name: PingMe-Action
  uses: kha7iq/pingme-action@v1

Usage

❯ pingme

NAME:
   PingMe - Send message to multiple platforms

USAGE:
   main [global options] command [command options] [arguments...]

DESCRIPTION:
   PingMe is a CLI tool which provides the ability to send messages or alerts to multiple
   messaging platforms and also email, everything is configurable via environment
   variables and command line switches.Currently supported platforms include Slack, Telegram,
   RocketChat, Discord, Pushover, Mattermost, Pushbullet, Microsoft Teams, Twillio, Mastodon,
   email address, Line, Gotify and Wechat.

COMMANDS:
   telegram    Send message to telegram
   rocketchat  Send message to rocketchat
   slack       Send message to slack
   discord     Send message to discord
   teams       Send message to microsoft teams
   pushover    Send message to pushover
   email       Send an email
   mattermost  Send message to mattermost
   pushbullet  Send message to pushbullet
   twillio     Send sms via twillio
   zulip       Send message to zulip
   mastodon    Set status message for mastodon
   line        Send message to line messenger
   wechat      Send message to wechat official account
   gotify      Send push notification to gotify server
   help, h     Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help (default: false)

Check Documentation Page for more details.

Configuration

All the flags have corresponding environment variables associated with it. You can either provide the value with flags or export to a variable.

View the Documentation Page for more details.

Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.

Acknowledgments

This project is based on amazing library Notify

pingme's Issues

feat(service): support for mastodon

Mastodon

Add support for the popular social network platform Mastodon.

Describe the solution you'd like
Mastodon has a rest api with comprehensive documentation which can be used to set status messages.

trouble to create slack token

in https://pingme.lmno.pk/#/services?id=slack
I know I need a "token" and a channel id to send message via pingme to slack.
the channel id iseasy to find URL ( click any of your channels , and get this URL https://app.slack.com/client/{ team_id} /{ channel_id } , is that correct ? )
but how to create a token ?
I try to create a token in apps

but which is the token pingme need ??
I try all these values in pingme , but always return

chc@hq39:~$ pingme slack -t "xxxxxxx758.373xxxxxxxx" --channel "D*****P32" --msg "test"
2022/06/29 15:10:53 failed to send message to Slack channel '' at time '': invalid_auth: send notification
chc@hq39:~$

is there any instructions to guide to create a valid token and get the channel id in slack for pingme ??

fix(mattermost): cleanup resonpse sent from server

Describe the bug
After a message is sent successfully or an error is returned the output is a json response.
cleanup the response and display only meaningful information.

Make Dockerfile to build from source

The current Dockerfile just copies the binary built outside of Docker to the image. It's not a source build (which is the most common use).

An official, built-in Dockerfile which allows to build a Docker image directly from source would be more useful.
Case in point: I wanted to test @ahdekkers' PR #65 and since building is quite an involved process for me and my Golang host OS' packages are outdated, I looked for a Dockerfile to build an image and attempted to build directly from the PR:

docker build --force-rm -t pingme github.com/kha7iq/pingme#pull/65/head

Unfortunately, since it's not a source build and it expects the binary to be built outside of the Docker workflow, it didn't work for me.

Potential use-cases for a source build Dockerfile:

• Running: With a proper Dockerfile, you could just issue a docker build -t pingme github.com/kha7iq/pingme#master to locally build a Docker image ready to run with a simple docker run. No build tools needed, no packaging, not even cloning the repo! And it would be straight from source (any desired branch or tag).
• Development: You can start hacking right away with just Docker installed without needing any further toolchain on your system, since the only thing needed to test your code is docker build ....
• Distribution: You can use the same workflow which works locally to build the images and push them to Docker Hub (even for other architectures) with a simple Github Action. Thus, you'll have a public Docker image with the latest code on HEAD (aka. daily builds).
• Documentation: since the Dockerfile should install all required build tools, libraries and other packages and would require also to run all the required build commands, it would serve as reference to the build process.

Support for carriage return \n

Is your feature request related to a problem? Please describe.

I was not able to send a msg (for instance via teams) with carriage return in it (\n Linux). Is there a way to achieve it?

Describe the solution you'd like

Sending a msg in form of:
pingme teams -w TOKEN --msg "Hi, I got a**\n** carriage return. Nice!"

Describe alternatives you've considered

Over ways to pass it will be totally acceptable

Additional context

PingMe version 0.2.4
NAME="Linux Mint"
VERSION="20.2 (Uma)"
ID=linuxmint
ID_LIKE=ubuntu

A great thank you for you're implementation of nikoksr/notify!

gzip error when installing

Describe the bug
i am trying to install it on raspberry pi 4 but i get the following error

gzip: stdin: not in gzip format
tar: Child returned status 1
tar: Error is not recoverable: exiting now

To Reproduce

Steps to reproduce the behavior:

curl -s https://raw.githubusercontent.com/kha7iq/pingme/master/install.sh | sudo sh
Fetching latest version
Found version 0.2.6
Downloading pingme_0.2.6_Linux_aarch64.tar.gz

gzip: stdin: not in gzip format
tar: Child returned status 1
tar: Error is not recoverable: exiting now

Expected behavior

successful installation

Desktop (please complete the following information):

• OS: raspberry pi os 64 bit (ARM64)
• Version: Debian GNU/Linux 11 (bullseye)

Homebrew tap issue

Warning: Calling bottle :unneeded is deprecated! There is no replacement.
Please report this issue to the kha7iq/tap tap (not Homebrew/brew or Homebrew/core):
  /usr/local/Homebrew/Library/Taps/kha7iq/homebrew-tap/Formula/pingme.rb:10

add tests for supported services

At the moment there are no tests for most of the services, having tests for supported services will help greatly to keep the app stable.

Telegram
Slack
Pushover
Pushbullet
Ms Teams
RocketChat
Discord
Twillio

Can't send email without password

Describe the bug

2021/08/03 11:44:41 failed to send mail: smtp: server doesn't support AUTH: send notification
To Reproduce

Steps to reproduce the behavior:

1. send email without (empty) password

• OS: Ubuntu
• Version 0.2.3

feat(service): support for sending messages via Twillio

Is your feature request related to a problem? Please describe.
Add support for sending SMS through Twillio service

Describe the solution you'd like
Twillio has a rest api with comprehensive documentation and ability to setup a trail account with free credit for testing.
https://www.twilio.com/docs/sms/api

There is a library gotwillio for twillio service
some basic integration can be used for reference.

feat(service): add support for matrix server

Matrix is free and open source self hosted service. Adding it to the supported push services will be useful.

It's the back-end part of the formerly known Riot.im know called Element

Describe the solution you'd like

Server has an api which can be used to send messages.

Additional context

Some useful links:

• Matrix API Documentation
• Gist using Curl to communicate with matrix

feat(service): add support for pushbullet service

Is your feature request related to a problem?
Add support for pushbullet service, push messages and sms.

Describe the solution you'd like
Existing library already has support for both, it can be utilized in this regard.

Debian package warning: missing 'maintainer' field

Description
After installing pingme on Ubuntu Bionic via Debian package from the release page, now a dpkg message appears after each dpkginstallation:

dpkg: warning: analyzing /var/lib/dpkg/status near line 54890 package "pingme":
missing maintainer

Note: message is not meant to be literal, but a translation from my system's locale to English.
Additionally, removing package makes error message to go away.

To Reproduce

1. Install pingme from Debian package.
2. Perform any subsequent apt install (package upgrades, too).
3. Error is printed.

Expected behavior
No warning.

Desktop (please complete the following information):

• OS: Ubuntu Bionic
• Version: 18.04.6

docs: Minor spelling and grammatical fixes in "Services & Usage" page

Here, minor spelling and grammatical mistakes on the "Services & Usage" page that immediately caught the eyes were fixed.

strconv.Atoi: parsing "-1234567890123": value out of range

Describe the bug
Chat ID is producing error on ARM7L platform.

On x86 the function strconv.Atoi is working fine, but on a ARM platform with armv7l (Odroid XU4) the command pingme fails.

To Reproduce
Steps to reproduce the behavior:

$ pingme telegram --token "124:abcd" --title "Message title" --msg "My message" --channel="-1234567890123"

Expected behavior

The expected behavior is that the chat id is used to ping a telegram channel.

Desktop (please complete the following information):

• OS: Ubuntu 18.04.5 LTS
• Version: PingMe version 0.2.0

Additional context

The conversion of the string to an integer is working fine on a x86 desktop PC.
It seems that the 32 bit ARM Platform can not handle such big numbers, while a 64 bit architecture can handle it.

Source: service/telegram/telegram.go
chn := strings.Split(telegramOpts.Channel, ",") for _, v := range chn { if len(v) <= 0 { return helpers.ErrChannel } k, errStr := strconv.Atoi(v) if errStr != nil { return errStr } telegramSvc.AddReceivers(int64(k)) }
[ Zeile 81/102 (79%)]

feat(service): add support for textmagic service

Is your feature request related to a problem?
Add support for textmagic service.

Describe the solution you'd like
This app uses notify library for some integrations, textmagic service is supported by the library.
There is also a usage example, which can be help in adding support.
https://github.com/nikoksr/notify/tree/main/service/textmagic

email attachment

hello, I don't know if it is out of scope but it would be useful to be able to attach files as well as to be able to write a msg in html format.

thank you.

Arch Linux AUR package

I have created a AUR package that builds from the sources, it’s called pingme.

Please add it to the README.md.

feat(service): support for sending messages to Zulip chat

Is your feature request related to a problem?
Add support for sending messages to Zulip chat.

Describe the solution you'd like
Zulip has a rest api with comprehensive documentation and ability to setup a free account.
There is an example of how to send message via rest api here : https://zulipchat.com/api/send-message

Have a look at mattermost service you can use it as base of implementation.

pushover: possibility to use priority argument

Hi and thanks for your great tool!
I would like to be able to use the priority argument with your pingme tool for pushover, the go wrapper you are using ( https://github.com/gregdel/pushover ) has it already built in, so it should be not a significant effort to implement it into your code, but I can't program go so its hard for me to implement it myself :(
thank you and have a great day!
cheers Ringo

Move documentation pages from external repository

Is your feature request related to a problem?
Move documentation pages from external repository to have a single source for all changes.

Mattermost/HTTP

Describe the solution you'd like
An integration for Mattermost. A possibility to send a HTTP request would actually already be enough.

Describe alternatives you've considered
I now use a PHP script that calls an URL, but that requires PHP of course.

Add support for Pushover service

Is your feature request related to a problem?
Based on feedback from users, pushover support can be very useful.

Describe the solution you'd like
Pushover already has an API endpoint for integration, which can be utilized in this case.

feat(service): add support for gotify server

Gotify is free and open source self hostable service. Adding it to the supported push services will be useful.

Describe the solution you'd like

Server has an api which can be used to send messages.

Support Feishu

Not working on Raspberry Pi

sudo pingme
/usr/local/bin/pingme: 1: /usr/local/bin/pingme: Syntax error: "|" unexpected

When executing in Raspberry Pi 3 with Raspbian 9

Ability to send messages to users (not channels) in rocket chat

pingme is fantastic!

In addition to being able to send messages to rocket chat channels, it would be great to be able to send messages to specific users. However, I can't find a way to do it, or it is not implemented yet.

I would like to:

pingme --channel user --msg "hi!" --token $TOKEN --userid $MYUSER --url $URL

Thanks!

API support

Describe the solution you'd like
An API option to contact other services like a SMS provider

Additional context
Ensure with have all options needed to pass to the API

refactor: refactor and organize code for testing

Refactor and Restructure Project

Code needs to be restructured in order to have a better way of adding more services, and testing each service.
As new services are going to be added and tests must be included for each service, every service must be isolated from each other for testing.

feat(service): add support for whatsapp

Adding Whatsapp will be absolutely awesome.

Describe the solution you'd like

Based on the Notify service would it be possible to do this without huge work?
https://github.com/nikoksr/notify/tree/main/service/whatsapp

feat(service): add support for Line messanger

Is your feature request related to a problem?
Add support for sending messages to line messenger.

Describe the solution you'd like
This app uses notify library for some integrations, line is supported by this library.
There is also a usage example, which can be help in adding support.
https://github.com/nikoksr/notify/blob/main/service/line/usage.md

Add multi arch docker image

Is your feature request related to a problem?
A Docker image is needed in users want to use this in pipelines.
Process should be automated for new each release

Describe the solution you'd like
We can use goreleaser to include image builds and pushed to dockerhub and ghcr.io

Credits section in readme

Hey @kha7iq, I remember you once contributed to notify; thanks again for that and congratulations for your great and successful project here!

I stumbled across your project through godoc and to be honest was a bit irritated that you took parts of the readme from notify (which is perfectly fine) but explicitly removed the Credits section. Like your project, notify stands on the shoulders of giants and the least we can do is give credit to those projects. Of course you can't credit every single project but if a project like yours (pingme) is based to such a large extent on a single project (notify) then we would be very grateful if you would at least credit us in your readme; especially since you yourself are part of the notify contributors.

Best regards and happy coding!