# tg-rs
[](https://crates.io/crates/tg-cli)
[](https://github.com/Garfield1002/tg-rs/blob/HEAD/LICENSE.md)
> ⚠️ This is a potentially dangerous vibe coded project. Use at your own risk.
Send yourself Telegram messages from the command line.
```sh
tg "Hello, World!"
## Install
Requires Rust. Clone the repo and build:
```sh
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](https://t.me/BotFather).
```sh
tg setup
```
## Usage
```
tg [OPTIONS] [MESSAGE...]
tg <SUBCOMMAND>
```
### Send a message
```sh
# Positional args (joined with spaces)
tg hello world
tg "I'm a fun message"
# From stdin
tg < /etc/hostname
```
If no message args are given, `tg` reads from stdin until EOF.
### Options
| `-p NAME` | `--profile NAME` | Profile to use (overrides `TG_PROFILE` env var) |
| `-e` | | Interpret escape sequences (`\n`, `\t`, `\\`) |
| `-n` | | Strip trailing newline from input |
| `-m MODE` | `--parse-mode MODE` | Telegram formatting: `markdown` or `html` |
| `-i` | `--interactive` | Stream stdin updates by editing one message (max 1/s) |
| `-f` | `--interactive-frequency SECONDS` | Seconds between interactive updates (default: `1`) |
| `-s` | `--silent` | Send without device notification |
| `-q` | `--quiet` | Suppress non-error output |
| `-h` | `--help` | Show help |
| `-V` | `--version` | Show version |
### Escape sequences (`-e`)
```sh
tg -e "line one\nline two"
tg -e "col1\tcol2"
```
### Telegram formatting (`-m`)
```sh
# 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](https://core.telegram.org/bots/api#markdownv2-style) 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:
```sh
tg -s "nightly backup finished"
```
### Combining flags
```sh
# Multiline silent message
tg -e -s "backup complete\nfiles: 1,042\nsize: 4.2 GB"
# Piped log with no notification
# 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.
```sh
# Example progress stream
# Update every 2 seconds
# 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;
### Profiles (`-p` / `--profile`)
Profiles let you send to different bots or chats without changing your default config.
```sh
# 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:
```sh
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.
```sh
# 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.
```sh
tg listen > out.txt
```
## Subcommands
### `tg setup`
Run the interactive setup to configure your chat ID. Only needed once.
```sh
tg setup
```
### `tg listen`
Listen for new incoming messages in the configured chat and write them to stdout until `/eof` is received.
```sh
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.
```sh
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:
```sh
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:
```sh
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>]`:
```toml
# 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
```sh
# Send a quick note
tg "Hello from the terminal"
# Results from a script
# 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:
```rust
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(...)`:
```rust
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
```toml
[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/>