tg-rs

⚠️ This is a potentially dangerous vibe coded project. Use at your own risk.

Send yourself Telegram messages from the command line.

tg "Hello, World!"
echo "Hello, World!" | tg

Install

Requires Rust. Clone the repo and build:

git clone https://github.com/Garfield1002/tg-rs
cd tg-rs
cargo install --path .

Setup

Run the interactive setup once. You will need a Telegram bot token, you can create one via @BotFather.

tg setup

Usage

tg [OPTIONS] [MESSAGE...]
tg <SUBCOMMAND>

Send a message

# Positional args (joined with spaces)
tg hello world
tg "I'm a fun message"

# From stdin
echo "hello" | tg
cat LICENSE.md | tg
tg < /etc/hostname

If no message args are given, tg reads from stdin until EOF.

Options

Escape sequences (-e)

tg -e "line one\nline two"
tg -e "col1\tcol2"

Telegram formatting (-m)

# MarkdownV2
tg -m markdown "*bold* _italic_ \`code\`"

# HTML
tg -m html "<b>bold</b> <i>italic</i> <code>code</code>"

Note: MarkdownV2 requires special characters to be escaped. See the Telegram docs for details. tg automatically escapes these characters for you

Silent notifications (-s)

Sends the message without triggering a sound or notification banner on the recipient's device. Useful for low-priority automated alerts:

tg -s "nightly backup finished"

Combining flags

# Multiline silent message
tg -e -s "backup complete\nfiles: 1,042\nsize: 4.2 GB"

# Piped log with no notification
cat /etc/hostname | tg -s

# HTML alert
tg -m html "<b>ERROR</b>: service crashed"

Interactive updates (-i)

Use interactive mode for progress-like output. The first update sends a message, then further updates edit that same message with a max rate of 1 update per second.

Use --interactive-frequency (-f) to change the update interval.

# Example progress stream
some-command-that-prints-progress | tg -i

# Update every 2 seconds
some-command-that-prints-progress | tg -i --interactive-frequency 2

# ASCII progress bar stream (bash)
for i in $(seq 0 20); do
    filled=$(printf '%*s' "$i" '' | tr ' ' '#');
    empty=$(printf '%*s' "$((20 - i))" '' | tr ' ' '-');
    printf '\r`[%s%s] %3d%%`' "$filled" "$empty" "$((i * 5))";
    sleep 0.5;
done | tg -i

Profiles (-p / --profile)

Profiles let you send to different bots or chats without changing your default config.

# Set up a named profile
tg setup --profile work
tg setup --profile personal

# Send using a profile
tg --profile work "deploy finished"
tg -p personal "weekend plans"

# Select a profile via environment variable
TG_PROFILE=work tg "staging is up"
export TG_PROFILE=work
tg "this goes to work too"

# Profile-specific subcommands
tg -p work config show
tg -p work config reset
tg -p work attach report.pdf
tg -p work listen

--profile is a global flag accepted before or after the subcommand:

tg --profile work config reset
tg config reset --profile work   # equivalent

Attach files (tg attach)

Send one or more files as Telegram document attachments. Shell globbing works as expected.

# Single file
tg attach report.pdf

# Multiple files
tg attach foo.txt bar.c

# Glob pattern
tg attach *.log

# Silent attachment
tg attach -s backup.tar.gz

Listen mode (tg listen)

Listen for new incoming messages in the configured chat and write them to stdout. Listening stops when /eof is received.

tg listen > out.txt

Subcommands

tg setup

Run the interactive setup to configure your chat ID. Only needed once.

tg setup

tg listen

Listen for new incoming messages in the configured chat and write them to stdout until /eof is received.

tg listen > out.txt

tg attach

Send files as document attachments. Accepts one or more file paths; shell globbing is handled by the shell before tg sees the arguments.

tg attach *.png
tg attach -s large-file.zip   # silent
tg attach -q data.csv         # quiet (no "Sent:" output)

tg config show

Print configuration status without revealing secrets. When called without --profile, also lists all named profiles:

tg config show
# Config path: /home/user/.config/tg/config.toml
# Config file: present
# Chat ID: 123456789
# Secret Service: available
# Token: configured (Secret Service)
#
# Available profiles:
#   personal: Chat ID: 111222333, Token: configured (Secret Service)
#   work: Chat ID: 987654321, Token: configured (Secret Service)

# Inspect a specific profile
tg --profile work config show
# Profile: work
# Config path: /home/user/.config/tg/config.toml
# ...

tg config reset

Delete the config and keyring token for a profile so you can run setup again. Without --profile, resets the default:

tg config reset
tg setup

# Reset a named profile only (other profiles are unaffected)
tg --profile work config reset
tg --profile work setup

Configuration

tg stores bot tokens in Secret Service (GNOME Keyring / KWallet) when available. If unavailable, it falls back to plaintext in ~/.config/tg/config.toml and prints a warning.

All profiles share a single config file. The default profile lives at the top level; named profiles are under [profiles.<name>]:

# Default profile
chat_id = 123456789
# token = "..."   # plaintext fallback only

[profiles.work]
chat_id = 987654321

[profiles.personal]
chat_id = 111222333

Keyring entries follow the same pattern — "telegram-bot-token" for the default, "telegram-bot-token-<name>" for named profiles.

To reconfigure a profile, run tg [--profile NAME] config reset then tg [--profile NAME] setup.

Examples

# Send a quick note
tg "Hello from the terminal"

# Results from a script
ls | tg

# Multiline message
tg -e "Line 1\nLine 2\nLine 3"

# Bold alert via HTML
tg -m html "<b>ALERT</b>"

Library Macro

The crate exports a telegram! macro for quick fire-and-forget sends in Rust code:

use tg_cli::telegram;

#[tokio::main]
async fn main() {
    telegram!("build {} complete", 42);
}

Notes:

• telegram! uses Markdown parse mode and non-silent notifications.
• With default features, telegram! is non-blocking and does not need .await.
• Non-blocking behavior is controlled by the non-blocking feature.
• If non-blocking is disabled, telegram! uses a blocking send path.
• Send failures are printed to stderr.
• The macro reads TG_PROFILE at runtime to select a profile.
• For explicit error handling or custom parse/silent/profile options, use send_tg_message(...) directly.

Blocking API

If you want a synchronous API, call send_tg_message_blocking(...):

use tg_cli::{ParseMode, send_tg_message_blocking};

fn main() {
    if let Err(err) = send_tg_message_blocking("hello".to_string(), ParseMode::Markdown, false, None) {
        eprintln!("{err}");
    }
}

Feature Flags

[dependencies]
tg = { version = "0.1", default-features = false }

• Enable non-blocking to make telegram! use tokio::spawn.
• Disable non-blocking to make telegram! use blocking sends.

License

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to https://unlicense.org/