Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/msoap/shell2telegram

Telegram bot constructor from command-line
https://github.com/msoap/shell2telegram

docker golang server shell telegram telegram-bots

Last synced: 5 days ago
JSON representation

Telegram bot constructor from command-line

Awesome Lists containing this project

README 

        
 shell2telegram

-----------------------------------------------------------------------------------------------------------------------------------------



[![Go build status](https://github.com/msoap/shell2telegram/actions/workflows/go.yml/badge.svg)](https://github.com/msoap/shell2telegram/actions/workflows/go.yml)

[![Coverage Status](https://coveralls.io/repos/github/msoap/shell2telegram/badge.svg?branch=master)](https://coveralls.io/github/msoap/shell2telegram?branch=master)

[![Docker Pulls](https://img.shields.io/docker/pulls/msoap/shell2telegram.svg?maxAge=3600)](https://hub.docker.com/r/msoap/shell2telegram/)

[![Homebrew formula exists](https://img.shields.io/badge/homebrew-🍺-d7af72.svg)](https://github.com/msoap/shell2telegram#install)

[![Report Card](https://goreportcard.com/badge/github.com/msoap/shell2telegram)](https://goreportcard.com/report/github.com/msoap/shell2telegram)



Create Telegram bot from command-line



Install

-------



MacOS:



    brew tap msoap/tools

    brew install shell2telegram

    # update:

    brew upgrade shell2telegram



Or download binaries from: [releases](https://github.com/msoap/shell2telegram/releases) (OS X/Linux/Windows/RaspberryPi)



Or build from source:



    # set $GOPATH if needed

    go install github.com/msoap/shell2telegram@latest

    ln -s $GOPATH/bin/shell2telegram ~/bin/shell2telegram # or add $GOPATH/bin to $PATH



Or build image and run with Docker.

Example of `test-bot.Dockerfile` for bot who say current date:



    FROM msoap/shell2telegram

    # may be install some alpine packages:

    # RUN apk add --no-cache ...

    ENV TB_TOKEN=*******

    CMD ["/date", "date"]



And build and run:



    docker build -f test-bot.Dockerfile -t test-bot .

    docker run --rm test-bot

    # or run with set token from command line

    docker run -e TB_TOKEN=******* --rm test-bot



Using snap (Ubuntu or any Linux distribution with snap):



    # install stable version:

    sudo snap install shell2telegram

    

    # install the latest version:

    sudo snap install --edge shell2telegram

    

    # update

    sudo snap refresh shell2telegram



Notice: the snap-package has its own sandbox with the `/bin`, `/usr/bin` directories which are not equal to system-wide `PATH` directories.



Usage

-----



Get token from [BotFather bot](https://telegram.me/BotFather), and set TB_TOKEN var in shell



    export TB_TOKEN=*******

    shell2telegram [options] /chat_command 'shell command' /chat_command2 'shell command2'

    options:

        -allow-users= : telegram users who are allowed to chat with the bot ("user1,user2")

        -root-users=  : telegram users, who confirms new users in their private chat ("user1,user2")

        -allow-all           : allow all users (DANGEROUS!)

        -add-exit            : adding "/shell2telegram exit" command for terminate bot (for roots only)

        -log-commands        : logging all commands

        -tb-token=    : setting bot token (or set TB_TOKEN variable)

        -timeout=N           : setting timeout for bot (default 60 sec)

        -description= : setting description of bot

        -bind-addr=
 : address to listen incoming webhook requests

        -webhook=       : url for registering a webhook

        -persistent-users    : load/save users from file (default ~/.config/shell2telegram.json)

        -users-db= : file for store users

        -cache=N             : caching command out for N seconds

        -one-thread          : run each shell command in one thread

        -public              : bot is public (don't add /auth* commands)

        -sh-timeout=N        : set timeout for execute shell command (in seconds)

        -shell="shell"       : shell for execute command, "" - without shell (default "sh")

        -version

        -help



If not define -allow-users/-root-users options - authorize users via secret code from console or via chat with exists root users.



All text after /chat_command will be sent to STDIN of shell command.



Special chat commands

---------------------



for private chats only:



  * `/:plain_text` - get user message without any /command.



TODO:



  * `/:image` - for get image from user. Example: `/:image 'cat > file.jpg; echo ok'`

  * `/:file`  - for get file from user

  * `/:location`  - for get geo-location from user



Possible long-running shell processes (for example alarm/timer bot).



Autodetect images (png/jpg/gif/bmp) out from shell command, for example: `/get_image 'cat file.png'`



Setting environment variables for shell commands:



  * S2T_LOGIN - telegram @login (may be empty)

  * S2T_USERID - telegram user ID

  * S2T_USERNAME - telegram user name

  * S2T_CHATID - chat ID



Modificators for bot commands

-----------------------------



  * `:desc` - setting the description of command, `/cmd:desc="Command name" 'shell cmd'`

  * `:vars` - to create environment variables instead of text output to STDIN, `/cmd:vars=VAR1,VAR2 'echo $VAR1 / $VAR2'`

  * `:md` - to send message as markdown text, `/cmd:md 'echo "*bold* and _italic_"'`



TODO:



  * `/cmd:cron=3600` — periodic exec command, `/cmd:on args` - on, `/cmd:off` - off



Predefined bot commands

-----------------------



  * `/help` - list available commands

  * `/auth` - begin authorize new user

  * `/auth ` - authorize with code from console or from exists root user

  * `/authroot` - same for new root user

  * `/authroot ` - same for new root user



for root users only:



  * `/shell2telegram stat` - show users statistics

  * `/shell2telegram search ` - search users by name/id

  * `/shell2telegram ban ` - ban user

  * `/shell2telegram exit` - terminate bot (for run with -add-exit)

  * `/shell2telegram desc ` - set bot description

  * `/shell2telegram rm ` - delete command

  * `/shell2telegram broadcast_to_root ` - send message to all root users in private chat

  * `/shell2telegram message_to_user  ` - send message to user in private chat

  * `/shell2telegram version` - show version



Examples

--------



    # system information

    shell2telegram /top:desc="System information" 'top -l 1 | head -10' /date 'date' /ps 'ps aux -m | head -20'

    

    # sort any input

    shell2telegram /:plain_text sort

    

    # alarm bot:

    # /alarm time_in_seconds message

    shell2telegram /alarm:vars=SLEEP,MSG 'sleep $SLEEP; echo Hello $S2T_USERNAME; echo Alarm: $MSG'

    

    # sound volume control via telegram (Mac OS)

    shell2telegram /get  'osascript -e "output volume of (get volume settings)"' \

                   /up   'osascript -e "set volume output volume (($(osascript -e "output volume of (get volume settings)")+10))"' \

                   /down 'osascript -e "set volume output volume (($(osascript -e "output volume of (get volume settings)")-10))"'



    # using with webhook instead of poll

    shell2telegram -bind-addr=0.0.0.0:8080 -webhook=https://bot.example.com/path/to/bot \

                   /date /date



    # command with Markdown formating, calendar in monospace font

    shell2telegram /cal:md 'echo "\`\`\`$(ncal)\`\`\`"'



Links

-----



  * [Telegram channel about shell2telegram](https://telegram.me/shell2telegram)

  * [About Telegram bots](https://core.telegram.org/bots)

  * [Golang bindings for the Telegram Bot API](https://github.com/go-telegram-bot-api/telegram-bot-api)

  * [shell2http - shell commands as http-server](https://github.com/msoap/shell2http)