shell2telegram.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "SHELL2TELEGRAM" "" "January 2022" "" ""
.
.SH "NAME"
\fBshell2telegram\fR
.
.SH "shell2telegram"
Create Telegram bot from command\-line
.
.SH "Install"
MacOS:
.
.IP "" 4
.
.nf

brew tap msoap/tools
brew install shell2telegram
# update:
brew upgrade shell2telegram
.
.fi
.
.IP "" 0
.
.P
Or download binaries from: releases \fIhttps://github\.com/msoap/shell2telegram/releases\fR (OS X/Linux/Windows/RaspberryPi)
.
.P
Or build from source:
.
.IP "" 4
.
.nf

# set $GOPATH if needed
go install github\.com/msoap/shell2telegram@latest
ln \-s $GOPATH/bin/shell2telegram ~/bin/shell2telegram # or add $GOPATH/bin to $PATH
.
.fi
.
.IP "" 0
.
.P
Or build image and run with Docker\. Example of \fBtest\-bot\.Dockerfile\fR for bot who say current date:
.
.IP "" 4
.
.nf

FROM msoap/shell2telegram
# may be install some alpine packages:
# RUN apk add \-\-no\-cache \.\.\.
ENV TB_TOKEN=*******
CMD ["/date", "date"]
.
.fi
.
.IP "" 0
.
.P
And build and run:
.
.IP "" 4
.
.nf

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
.
.fi
.
.IP "" 0
.
.P
Using snap (Ubuntu or any Linux distribution with snap):
.
.IP "" 4
.
.nf

# install stable version:
sudo snap install shell2telegram

# install the latest version:
sudo snap install \-\-edge shell2telegram

# update
sudo snap refresh shell2telegram
.
.fi
.
.IP "" 0
.
.P
Notice: the snap\-package has its own sandbox with the \fB/bin\fR, \fB/usr/bin\fR directories which are not equal to system\-wide \fBPATH\fR directories\.
.
.SH "Usage"
Get token from BotFather bot \fIhttps://telegram\.me/BotFather\fR, and set TB_TOKEN var in shell
.
.IP "" 4
.
.nf

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
.
.fi
.
.IP "" 0
.
.P
If not define \-allow\-users/\-root\-users options \- authorize users via secret code from console or via chat with exists root users\.
.
.P
All text after /chat_command will be sent to STDIN of shell command\.
.
.SH "Special chat commands"
for private chats only:
.
.IP "\(bu" 4
\fB/:plain_text\fR \- get user message without any /command\.
.
.IP "" 0
.
.P
TODO:
.
.IP "\(bu" 4
\fB/:image\fR \- for get image from user\. Example: \fB/:image \'cat > file\.jpg; echo ok\'\fR
.
.IP "\(bu" 4
\fB/:file\fR \- for get file from user
.
.IP "\(bu" 4
\fB/:location\fR \- for get geo\-location from user
.
.IP "" 0
.
.P
Possible long\-running shell processes (for example alarm/timer bot)\.
.
.P
Autodetect images (png/jpg/gif/bmp) out from shell command, for example: \fB/get_image \'cat file\.png\'\fR
.
.P
Setting environment variables for shell commands:
.
.IP "\(bu" 4
S2T_LOGIN \- telegram @login (may be empty)
.
.IP "\(bu" 4
S2T_USERID \- telegram user ID
.
.IP "\(bu" 4
S2T_USERNAME \- telegram user name
.
.IP "\(bu" 4
S2T_CHATID \- chat ID
.
.IP "" 0
.
.SH "Modificators for bot commands"
.
.IP "\(bu" 4
\fB:desc\fR \- setting the description of command, \fB/cmd:desc="Command name" \'shell cmd\'\fR
.
.IP "\(bu" 4
\fB:vars\fR \- to create environment variables instead of text output to STDIN, \fB/cmd:vars=VAR1,VAR2 \'echo $VAR1 / $VAR2\'\fR
.
.IP "\(bu" 4
\fB:md\fR \- to send message as markdown text, \fB/cmd:md \'echo "*bold* and _italic_"\'\fR
.
.IP "" 0
.
.P
TODO:
.
.IP "\(bu" 4
\fB/cmd:cron=3600\fR — periodic exec command, \fB/cmd:on args\fR \- on, \fB/cmd:off\fR \- off
.
.IP "" 0
.
.SH "Predefined bot commands"
.
.IP "\(bu" 4
\fB/help\fR \- list available commands
.
.IP "\(bu" 4
\fB/auth\fR \- begin authorize new user
.
.IP "\(bu" 4
\fB/auth <CODE>\fR \- authorize with code from console or from exists root user
.
.IP "\(bu" 4
\fB/authroot\fR \- same for new root user
.
.IP "\(bu" 4
\fB/authroot <CODE>\fR \- same for new root user
.
.IP "" 0
.
.P
for root users only:
.
.IP "\(bu" 4
\fB/shell2telegram stat\fR \- show users statistics
.
.IP "\(bu" 4
\fB/shell2telegram search <query>\fR \- search users by name/id
.
.IP "\(bu" 4
\fB/shell2telegram ban <user_id|@username>\fR \- ban user
.
.IP "\(bu" 4
\fB/shell2telegram exit\fR \- terminate bot (for run with \-add\-exit)
.
.IP "\(bu" 4
\fB/shell2telegram desc <description>\fR \- set bot description
.
.IP "\(bu" 4
\fB/shell2telegram rm </command>\fR \- delete command
.
.IP "\(bu" 4
\fB/shell2telegram broadcast_to_root <message>\fR \- send message to all root users in private chat
.
.IP "\(bu" 4
\fB/shell2telegram message_to_user <user_id|@username> <message>\fR \- send message to user in private chat
.
.IP "\(bu" 4
\fB/shell2telegram version\fR \- show version
.
.IP "" 0
.
.SH "Examples"
.
.nf

# 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)"\' \e
               /up   \'osascript \-e "set volume output volume (($(osascript \-e "output volume of (get volume settings)")+10))"\' \e
               /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 \e
               /date /date

# command with Markdown formating, calendar in monospace font
shell2telegram /cal:md \'echo "\e`\e`\e`$(ncal)\e`\e`\e`"\'
.
.fi
.
.SH "Links"
.
.IP "\(bu" 4
Telegram channel about shell2telegram \fIhttps://telegram\.me/shell2telegram\fR
.
.IP "\(bu" 4
About Telegram bots \fIhttps://core\.telegram\.org/bots\fR
.
.IP "\(bu" 4
Golang bindings for the Telegram Bot API \fIhttps://github\.com/go\-telegram\-bot\-api/telegram\-bot\-api\fR
.
.IP "\(bu" 4
shell2http \- shell commands as http\-server \fIhttps://github\.com/msoap/shell2http\fR
.
.IP "" 0