Home

Awesome

<img src="https://raw.githubusercontent.com/msoap/shell2telegram/misc/img/shell2telegram_icon.png" width="32" height="32"> shell2telegram

Go build status Coverage Status Docker Pulls Homebrew formula exists Report Card

Create Telegram bot from command-line

Install

MacOS:

brew tap msoap/tools
brew install shell2telegram
# update:
brew upgrade shell2telegram

Or download binaries from: 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, and set TB_TOKEN var in shell

export TB_TOKEN=*******
shell2telegram [options] /chat_command 'shell command' /chat_command2 'shell command2'
options:
    -allow-users=<NAMES> : telegram users who are allowed to chat with the bot ("user1,user2")
    -root-users=<NAMES>  : 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=<TOKEN>    : setting bot token (or set TB_TOKEN variable)
    -timeout=N           : setting timeout for bot (default 60 sec)
    -description=<TITLE> : setting description of bot
    -bind-addr=<ADDRESS> : address to listen incoming webhook requests
    -webhook=<URL>       : url for registering a webhook
    -persistent-users    : load/save users from file (default ~/.config/shell2telegram.json)
    -users-db=<FILENAME> : 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:

TODO:

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:

Modificators for bot commands

TODO:

Predefined bot commands

for root users only:

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