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 (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:
/: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 <CODE>- authorize with code from console or from exists root user/authroot- same for new root user/authroot <CODE>- same for new root user
for root users only:
/shell2telegram stat- show users statistics/shell2telegram search <query>- search users by name/id/shell2telegram ban <user_id|@username>- ban user/shell2telegram exit- terminate bot (for run with -add-exit)/shell2telegram desc <description>- set bot description/shell2telegram rm </command>- delete command/shell2telegram broadcast_to_root <message>- send message to all root users in private chat/shell2telegram message_to_user <user_id|@username> <message>- 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)\`\`\`"'