# cli2telegram
Small utility to send Telegram messages from the CLI.
This can f.ex. be used to
* quickly send arbitrary messages to a Telegram chat of your choice
* use it as a replacement for the "mail" program on linux
* use Telegram as a notification backend for the ZFS Event Daemon (zed)
## Features
* [x] Read messages from argument or STDIN
* [x] (Optional) Configuration file
* [x] Retry sending messages for a specified amount of time
* [x] Handling of long messages
* [x] Run as a daemon and echo messages into a linux pipe
## Examples
```shell
cli2telegram -h
# From arguments
cli2telegram "This is a message"
cli2telegram "Header" "This is a multiline message."
# From STDIN
echo My Message | cli2telegram
printf "Header\nThis is a multiline message." | cli2telegram
# Config via parameters
printf "Message" | cli2telegram -b "123456789:ABCDEFG" -c "123456789"
# Config via parameters and send message in a code block
printf "Message" | cli2telegram -b "123456789:ABCDEFG" -c "123456789" -C
# as a Daemon
cli2telegram -d -p "/tmp/cli2telegram"
echo "hello world!" > /tmp/cli2telegram
```
# Install
To use this utility install it either using:
```
pip install cli2telegram
```
or - if you don't want to install it globally - using f.ex. [venv-install](https://github.com/markusressel/venv-install):
```
venv-install cli2telegram cli2telegram
```
or your custom `venv` manager of choice.
# Configuration
To be able to send you messages you have to provide a **bot token** and a **chat id**.
You can configure cli2telegram using cli parameters, a configuration file,
environment variables, or a combination of them.
## Parameters
| Name | Type | Description |
|----------------------|--------|-------------------------------------------|
| `-b`, `--bot-token` | String | Telegram Bot Token |
| `-c`, `--chat-id` | String | Telegram Chat ID |
| `-C`, `--code-block` | String | Send message inside a code block |
| `-d`, `--daemon` | Flag | Run as a daemon |
| `-p`, `--pipe` | String | File path to the pipe used in daemon mode |
## File
cli2telegram uses [container-app-conf](https://github.com/markusressel/container-app-conf) so you can use YAML, TOML, or ENV to set those.
Have a look at the [cli2telegram.toml_example](cli2telegram.toml_example) file to get an idea.
# Daemon
When running cli2telegram as a daemon, the pipe will close for a brief amount of time between receiving input messages.
If you are sending multiple messages to the pipe using f.ex. a script, make sure to wait a bit (f.ex. 0.5 seconds)
between sending messages, otherwise:
* multiple messages may be received as one
* messages may get lost
* you may receive a `Broken pipe` error
# Use Cases
## ZFS Event Daemon (ZED)
To make `zed` call cli2telegram we will trick it and make it use cli2telegram as an E-Mail client.
Edit `/etc/zfs/zed.d/zed.rc` as root:
```bash
sudo nano -w /etc/zfs/zed.d/zed.rc
```
and
* uncomment `ZED_EMAIL_ADDR`, the value does not matter since we use our own email script, but **it is necessary to set a value to make ZED send 'emails'**
* set `ZED_EMAIL_PROG` to the path of the script, f.ex. `/usr/bin/cli2telegram`
* it is important to note that zed does not seem to work if your command needs arguments to run
```
# this must not be empty!
ZED_EMAIL_ADDR="root"
[...]
ZED_EMAIL_PROG="/usr/bin/cli2telegram"
[...]
# this must not be empty!
ZED_EMAIL_OPTS="#zfs #$(hostname)"
[...]
# If you want to receive email no matter the state of your pool, you’ll want to set:
ZED_NOTIFY_VERBOSE=1
[...]
```
Since `zed` will run your scripts as root, if you want to use a config file
you have to put it in f.ex. `/root/.config/cli2telegram.toml`.
# Contributing
GitHub is for social coding: if you want to write code, I encourage contributions through pull requests from forks
of this repository. Create GitHub tickets for bugs and new features and comment on the ones that you are interested in.
# License
```text
cli2telegram by Markus Ressel
Copyright (C) 2018 Markus Ressel
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/markusressel/cli2telegram",
"name": "cli2telegram",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "cli,telegram,notification",
"author": "Markus Ressel",
"author_email": "mail@markusressel.de",
"download_url": "https://files.pythonhosted.org/packages/a0/de/1685e5af8ecc5f99ced215ca4894c7c7bff142e133d3496adf1291b43ee9/cli2telegram-2.0.1.tar.gz",
"platform": null,
"description": "# cli2telegram\nSmall utility to send Telegram messages from the CLI.\n\nThis can f.ex. be used to\n* quickly send arbitrary messages to a Telegram chat of your choice\n* use it as a replacement for the \"mail\" program on linux\n* use Telegram as a notification backend for the ZFS Event Daemon (zed)\n\n## Features\n* [x] Read messages from argument or STDIN\n* [x] (Optional) Configuration file\n* [x] Retry sending messages for a specified amount of time\n* [x] Handling of long messages\n* [x] Run as a daemon and echo messages into a linux pipe\n\n## Examples\n\n```shell\ncli2telegram -h\n\n# From arguments\ncli2telegram \"This is a message\"\n\ncli2telegram \"Header\" \"This is a multiline message.\"\n\n# From STDIN\necho My Message | cli2telegram\n\nprintf \"Header\\nThis is a multiline message.\" | cli2telegram\n\n# Config via parameters\nprintf \"Message\" | cli2telegram -b \"123456789:ABCDEFG\" -c \"123456789\"\n\n# Config via parameters and send message in a code block\nprintf \"Message\" | cli2telegram -b \"123456789:ABCDEFG\" -c \"123456789\" -C\n\n# as a Daemon\ncli2telegram -d -p \"/tmp/cli2telegram\"\necho \"hello world!\" > /tmp/cli2telegram\n``` \n\n# Install\n\nTo use this utility install it either using:\n```\npip install cli2telegram\n```\n\nor - if you don't want to install it globally - using f.ex. [venv-install](https://github.com/markusressel/venv-install):\n```\nvenv-install cli2telegram cli2telegram\n```\n\nor your custom `venv` manager of choice.\n\n# Configuration\n\nTo be able to send you messages you have to provide a **bot token** and a **chat id**.\nYou can configure cli2telegram using cli parameters, a configuration file,\nenvironment variables, or a combination of them.\n\n## Parameters\n\n| Name | Type | Description |\n|----------------------|--------|-------------------------------------------|\n| `-b`, `--bot-token` | String | Telegram Bot Token |\n| `-c`, `--chat-id` | String | Telegram Chat ID |\n| `-C`, `--code-block` | String | Send message inside a code block |\n| `-d`, `--daemon` | Flag | Run as a daemon |\n| `-p`, `--pipe` | String | File path to the pipe used in daemon mode |\n\n## File\ncli2telegram uses [container-app-conf](https://github.com/markusressel/container-app-conf) so you can use YAML, TOML, or ENV to set those.\n\nHave a look at the [cli2telegram.toml_example](cli2telegram.toml_example) file to get an idea.\n\n# Daemon\n\nWhen running cli2telegram as a daemon, the pipe will close for a brief amount of time between receiving input messages.\nIf you are sending multiple messages to the pipe using f.ex. a script, make sure to wait a bit (f.ex. 0.5 seconds)\nbetween sending messages, otherwise:\n* multiple messages may be received as one\n* messages may get lost\n* you may receive a `Broken pipe` error\n\n# Use Cases\n\n## ZFS Event Daemon (ZED)\nTo make `zed` call cli2telegram we will trick it and make it use cli2telegram as an E-Mail client.\n\nEdit `/etc/zfs/zed.d/zed.rc` as root:\n```bash\nsudo nano -w /etc/zfs/zed.d/zed.rc\n```\n\nand\n* uncomment `ZED_EMAIL_ADDR`, the value does not matter since we use our own email script, but **it is necessary to set a value to make ZED send 'emails'**\n* set `ZED_EMAIL_PROG` to the path of the script, f.ex. `/usr/bin/cli2telegram`\n * it is important to note that zed does not seem to work if your command needs arguments to run\n```\n# this must not be empty!\nZED_EMAIL_ADDR=\"root\"\n\n[...]\n\nZED_EMAIL_PROG=\"/usr/bin/cli2telegram\"\n\n[...]\n\n# this must not be empty!\nZED_EMAIL_OPTS=\"#zfs #$(hostname)\"\n\n[...]\n\n# If you want to receive email no matter the state of your pool, you\u2019ll want to set:\nZED_NOTIFY_VERBOSE=1\n\n[...]\n```\n\nSince `zed` will run your scripts as root, if you want to use a config file \nyou have to put it in f.ex. `/root/.config/cli2telegram.toml`.\n\n# Contributing\n\nGitHub is for social coding: if you want to write code, I encourage contributions through pull requests from forks\nof this repository. Create GitHub tickets for bugs and new features and comment on the ones that you are interested in.\n\n# License\n\n```text\ncli2telegram by Markus Ressel\nCopyright (C) 2018 Markus Ressel\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU Affero General Public License as\npublished by the Free Software Foundation, either version 3 of the\nLicense, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License\nalong with this program. If not, see <https://www.gnu.org/licenses/>.\n```\n\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Small utility to send Telegram messages from the CLI.",
"version": "2.0.1",
"split_keywords": [
"cli",
"telegram",
"notification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3dd724ca7d7e6120bf7410fd078417fec28611594c9f78a73a76c6697e862467",
"md5": "6db73c49542903c90e06e05b5e8548dd",
"sha256": "384affd7d6178d1c9415ad7997fb401f2fffa8abf4e922ebf94b2be6ef5d6ff2"
},
"downloads": -1,
"filename": "cli2telegram-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6db73c49542903c90e06e05b5e8548dd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 23431,
"upload_time": "2023-03-23T15:32:15",
"upload_time_iso_8601": "2023-03-23T15:32:15.558718Z",
"url": "https://files.pythonhosted.org/packages/3d/d7/24ca7d7e6120bf7410fd078417fec28611594c9f78a73a76c6697e862467/cli2telegram-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a0de1685e5af8ecc5f99ced215ca4894c7c7bff142e133d3496adf1291b43ee9",
"md5": "4efb29e906f7ce80089d31a4f3aeadda",
"sha256": "bd370c00c8d77f9b54f48527cd0b7d5c1baffcc5af8b279e3ed1827c038009f6"
},
"downloads": -1,
"filename": "cli2telegram-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "4efb29e906f7ce80089d31a4f3aeadda",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 20689,
"upload_time": "2023-03-23T15:32:17",
"upload_time_iso_8601": "2023-03-23T15:32:17.144320Z",
"url": "https://files.pythonhosted.org/packages/a0/de/1685e5af8ecc5f99ced215ca4894c7c7bff142e133d3496adf1291b43ee9/cli2telegram-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-23 15:32:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "markusressel",
"github_project": "cli2telegram",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cli2telegram"
}
JSON
