GRM - Group & Telegram Manager

C++23/TDLib Telegram CLI User & Operator Guide

Authors:

Rénich Bon Ćirić & Antigravity AI (Google DeepMind)

Contact:

renich@evalinux.com

Manual section:

1

Manual group:

User Commands

Description

grm is a high-performance, asynchronous CLI manager for Telegram built with modern C++23 and TDLib. It provides comprehensive create, read, update, and delete management for private chats, basic groups, supergroups, channels, stories, custom folders, and forum topics, alongside a robust file and media download engine.

Features

• Full Authentication Flow: Interactive or non-interactive phone code, QR code, and 2FA password verification.

• Complete CRUD Lifecycle: Full lifecycle support for chats, groups, forum topics, stories, folders, and text/media messages.

• File Download Engine: Batch download media attachments from chat history or specific forum topics with type filtering.

• Context-Aware Shell Autocompletion: Full Bash, Zsh, and Fish tab completion covering commands, subcommands, options, and parameters.

• Telegram Rich Text & Emoji Icons: Native Telegram Markdown entity parsing and custom supergroup topic and profile emoji icons.

• Multiple Output Formats: Supports human-readable tables, ANSI color, Markdown, JSON, JSONL/NDJSON, and CSV export.

• POSIX & GNU Standard Compliance: Supports GNU short/long option flags and positional parameters.

Synopsis

grm [global-options] <command> [<subcommand>] [options] [args]

Global Options

-h, --help

Show command or subcommand help message and exit.

-H, --help=all

Show exhaustive help screen for all commands and subcommands.

-V, --version

Display version, git commit, and build environment information.

-v, --verbose

Enable verbose TDLib log output to stdout.

-d, --debug

Enable low-level debug tracing and JSON payload logging.

-q, --quiet

Suppress informational messages and output only errors or data.

-c, --config <file>

Specify alternative path to configuration file (default: ~/.config/grm/config.json).

-T, --test-dc

Connect to Telegram Test Data Center (DC) environment.

-F, --format <fmt>

Set output format: human, markdown, json, jsonl (or ndjson), or plain (default: auto). Note: JSON format outputs compact single-line JSON by default.

-p, -P, --pretty

Pretty-print JSON output with multi-line indentation and spacing (when used with -F json).

-N, --name-format <fmt>

Set sender name display format: username (default, e.g. @username) or fullname (e.g. First Last).

-u, --username

Shortcut to set sender name format to username.

--full-name

Shortcut to set sender name format to fullname.

--color <mode>

Control ANSI color output: auto, always, or never (or --no-color).

Commands & Subcommands

Authentication

grm login [-p|–phone <num>] [-k|–code <code>] [-q|–qr]

Authenticate against Telegram servers using terminal phone code flow or browser QR code.

-p, --phone <num>

International phone number (e.g. +523330000000).

-k, --code <code>

SMS or Telegram login code.

-q, --qr

Authenticate via QR code by generating an interactive HTML QR code page and opening it via xdg-open.

grm logout

Log out from Telegram, terminate the active TDLib session, and clear local session state.

Chat & Group Management

grm chat ls [-n|–limit <N>] [-S|–since <duration|date>] [-f|–filter <pattern>]

List active chats, supergroups, channels, and private conversations.

-n, --limit <N>

Maximum number of chats to list (default: 100).

-S, --since <duration|date>

Filter chats active since natural duration (e.g. "1 day ago", "3 days ago", "2h"), ISO date, or timestamp.

-f, --filter <pattern>

Filter chats by title, type, or ID (case-insensitive substring or regex). Can be passed multiple times.

grm chat create group [–private|–public] “<title>”

Create a new basic group or supergroup.

grm chat create channel [–private|–public] “<title>” [“<description>”]

Create a new broadcast channel.

grm chat info <chat_id>

Display detailed JSON metadata for a specific chat or group.

grm chat set-title <chat_id> “<new_title>”

Update the title of a group or channel.

grm chat set-desc <chat_id> “<description>”

Update the description of a supergroup or channel.

grm chat pin <chat_id>

Pin a chat or group at the top of the chat list.

grm chat unpin <chat_id>

Unpin a chat or group from the top of the chat list.

grm chat delete <chat_id>

Delete chat history or leave group.

Message Lifecycle

grm msg ls [-n|–limit <N>] [-t|–topic <id>] [-S|–since <duration|date>] [-f|–filter <pattern>] [-r|–reverse] <chat_id>

List messages from a chat or forum topic in chronological order (oldest first at top, newest at bottom).

-n, --limit <N>

Maximum number of messages to display (default: 20).

-t, --topic <id>

Filter messages by forum topic ID.

-S, --since <duration|date>

Filter messages since natural human/systemd duration (e.g. "1 day ago", "3 days ago", "1 month ago", "2h", "30m", "yesterday", "today"), ISO date (YYYY-MM-DD), or Unix timestamp.

-f, --filter, --sender <pattern>

Filter messages by sender username, display name, or handle (case-insensitive substring or regex). Can be passed multiple times (e.g. --filter="renichbon" --filter="k_brown") to match any specified sender.

-r, --reverse

Display messages in reverse-chronological order (newest first at top).

grm msg pin <chat_id> <message_id>

Pin a specific message in a chat or supergroup.

grm msg unpin <chat_id> <message_id>

Unpin a specific message in a chat or supergroup.

grm msg unpin-all <chat_id>

Unpin all pinned messages in a chat or supergroup.

grm msg export [-f|–format csv|json] [-o|–output <file>] [-t|–topic <id>] <chat_id>

Export chat or topic history to a CSV or JSON file.

-f, --format <fmt>

Export file format: csv or json.

-o, --output <file>

Output target file path.

-t, --topic <id>

Target specific forum topic ID.

grm msg search [-q|–query “<query>”] [-n|–limit <N>] [-t|–topic <id>] [-S|–since <duration|date>] [-f|–filter <pattern>] <chat_id>

Search message history using query pattern or regex.

-q, –query “<query>”

Regex search pattern.

-n, --limit <N>

Maximum matching messages to return.

-t, --topic <id>

Target specific forum topic ID.

-S, --since <duration|date>

Filter messages since natural human/systemd duration (e.g. "1 day ago", "3 days ago", "1 month ago", "2h", "30m", "yesterday", "today"), ISO date (YYYY-MM-DD), or Unix timestamp.

-f, --filter, --sender <pattern>

Filter messages by sender username, display name, or handle (case-insensitive substring or regex).

grm msg send [-a|–attach <file>] [-m|–media] [-C|–caption “<text>”] [-t|–topic <id>] <chat_id> [“<message>”]

Send a text message, document, or media file attachment. Supports native Telegram Markdown formatting (**bold**, __italic__, ~~strike~~, ||spoiler||, inline/fenced code, links).

-a, --attach <file>

Path to local file attachment (repeatable).

-m, --media

Send attachment as compressed media (photo/video).

-C, –caption “<text>”

Caption text for file attachment.

-t, --topic <id>

Target specific forum topic ID.

grm msg info <chat_id> <message_id>

View detailed message JSON metadata.

grm msg edit <chat_id> <message_id> “<new_text>”

Edit sent text message content.

grm msg delete [–for-everyone] <chat_id> <message_ids…>

Delete one or more messages.

-e, --for-everyone

Delete message for all participants in group.

grm msg forward [–from <source_chat_id>] [–to <target_chat_id>] [-t|–topic <id>] [-c|–copy] [–remove-caption] <source_chat_id> <target_chat_id> <message_ids…>

Forward one or more messages to another chat or forum topic. Supports text, photos, videos, documents, audio, and media albums.

-f, --from <chat_id>

Source chat ID (optional when specified as first positional argument).

--to <chat_id>

Target chat ID (optional when specified as second positional argument).

-t, --topic <id>

Target forum topic ID in destination chat.

-c, --copy

Send messages as a fresh copy without original forward header attribution.

--remove-caption

Remove media captions from forwarded photos, videos, documents, or audio files.

Forum Topic Management

grm topic ls [-n|–limit <N>] [-S|–since <duration|date>] [-f|–filter <pattern>] <supergroup_id>

List active forum topics in a Telegram supergroup.

-n, --limit <N>

Maximum topics to list (default: 100).

-S, --since <duration|date>

Filter topics active since natural duration (e.g. "1 day ago", "3 days ago", "2h"), ISO date, or timestamp.

-f, --filter <pattern>

Filter topics by name or thread ID (case-insensitive substring or regex). Can be passed multiple times.

grm topic create [-e|–emoji <id>] [–icon-color <color>] <supergroup_id> “<topic_name>”

Create a new forum topic in a supergroup with optional custom emoji icon.

-e, --emoji, --icon <id>

Custom Telegram emoji icon identifier.

--icon-color <color>

RGB icon color hex integer (e.g. 0x6FB9F0).

grm topic info <supergroup_id> <topic_id>

View detailed metadata for a forum topic.

grm topic edit [-e|–emoji <id>] <supergroup_id> <topic_id> [“<new_name>”]

Rename an existing forum topic or change its custom emoji icon.

-e, --emoji, --icon <id>

Custom Telegram emoji icon identifier.

grm topic close <supergroup_id> <topic_id>

Close a forum topic.

grm topic reopen <supergroup_id> <topic_id>

Reopen a closed forum topic.

grm topic pin <supergroup_id> <topic_id>

Pin a forum topic.

grm topic unpin <supergroup_id> <topic_id>

Unpin a forum topic.

grm topic delete <supergroup_id> <topic_id>

Delete a forum topic and its history.

Story Management

grm story post [-f|–file <path>|-p|–photo <path>|-v|–video <path>] [–caption <caption>] [–privacy everyone|contacts|close_friends] [–period <time>] [–pinned] [–protect] [-l|–link <url>] [-r|–reaction <emoji>] [-C|–chat <id>]

Publish a new photo or video story with optional link and reaction sticker overlays.

-f, --file <path>

Path to local media file to publish as story (auto-detects photo or video by extension).

-p, --photo <path>

Path to local photo image file to publish as story.

-v, --video <path>

Path to local video file to publish as story.

-c, --caption <caption>

Story caption (supports URLs and Markdown formatting).

--privacy <setting>

Privacy setting: everyone (default), contacts, or close_friends.

--period <time>

Active story duration: 6h, 12h, 24h (default), or 48h.

--pinned

Pin story to chat page/profile under the permanent “Posts” tab (sets is_posted_to_chat_page: true).

--protect

Protect story content from saving and forwarding.

-l, --link <url>

Add a clickable link sticker overlay on the story.

-r, --reaction <emoji>

Add an interactive suggested reaction sticker button.

-C, --chat <id>

Target chat or channel ID (default: personal account).

grm story edit -s|–story-id <id> [–photo <path>|–video <path>] [–caption <caption>] [-l|–link <url>] [-r|–reaction <emoji>] [-C|–chat <id>]

Edit media content, caption, or interactive stickers of an existing story.

-s, --story-id <id>

Story identifier to edit.

-p, --photo <path>

New photo image file for story.

-v, --video <path>

New video file for story.

-c, --caption <caption>

New story caption.

-l, --link <url>

Add or update clickable link sticker overlay URL.

-r, --reaction <emoji>

Add or update interactive reaction button emoji.

-C, --chat <id>

Target chat or channel ID (default: personal account).

grm story info -s|–story-id <id> [-C|–chat <id>]

Display full story metadata, interaction counters, views, forwards, and attached interactive stickers.

-s, --story-id <id>

Story identifier to inspect.

-C, --chat <id>

Target chat or channel ID.

grm story viewers -s|–story-id <id> [-n|–limit <N>] [-q|–query <text>] [-C|–chat <id>]

List viewers and reactions for a story posted by your account.

-s, --story-id <id>

Story identifier.

-n, --limit <N>

Maximum number of viewers to display (default: 50).

-q, --query <text>

Filter viewers by name or username.

-C, --chat <id>

Target chat or channel ID.

grm story pin -s|–story-id <id> [-C|–chat <id>]

Pin an active story to your profile page under the permanent “Posts” tab.

-s, --story-id <id>

Story identifier to pin.

-C, --chat <id>

Target chat or channel ID.

grm story unpin -s|–story-id <id> [-C|–chat <id>]

Unpin a story from your profile page “Posts” tab.

-s, --story-id <id>

Story identifier to unpin.

-C, --chat <id>

Target chat or channel ID.

grm story react -s|–story-id <id> -e|–emoji <emoji> [-C|–chat <id>]

Set or remove a reaction on a story.

-s, --story-id <id>

Story identifier.

-e, --emoji <emoji>

Reaction emoji (pass empty string "" to remove reaction).

-C, --chat <id>

Target chat or channel ID.

grm story privacy -s|–story-id <id> –privacy <everyone|contacts|close_friends>

Update the privacy scope of an existing story.

-s, --story-id <id>

Story identifier to modify.

--privacy <setting>

New privacy scope (everyone, contacts, close_friends).

grm story stealth

Activate story stealth mode for 25 minutes, hiding your story views (Telegram Premium).

grm story ls [-C|–chat <id>] [-n|–limit <N>] [-p|–pinned] [-a|–archived] [-A|–all]

List active stories, pinned profile posts, and archived stories.

-C, --chat <id>

Target chat or channel ID (default: personal account).

-n, --limit <N>

Maximum number of stories to display (default: 20).

-p, --pinned, --posts

List stories posted to profile/chat page.

-a, --archived

List archived stories.

-A, --all

List active, pinned profile, and archived stories combined.

grm story delete -s|–story-id <id> [-C|–chat <id>]

Delete a published story by identifier.

-s, --story-id <id>

Story identifier to delete.

-C, --chat <id>

Target chat or channel ID (default: personal account).

Emoji Status Management

grm status ls [-f|–filter <query>] [-r|–recent] [-p|–packs] [<query>]

List and search available default, recent, and custom status emojis across installed packs (including official Animated Emoji).

-f, --filter <query>

Filter emojis by unicode character, description, pack name, or ID.

-r, --recent

Show recent custom emoji statuses.

-p, --packs

Show installed custom emoji packs.

grm status set -e|–emoji <id> [-d|–duration <time>] [-C|–chat <id>]

Set a custom Telegram emoji status badge.

-e, --emoji <id>

Custom Telegram emoji identifier (int64 string).

-d, --duration <time>

Status badge duration (e.g. 30m, 1h, 8h, 2d, 1w).

-C, --chat <id>

Target boosted channel or supergroup chat ID.

grm status clear [-C|–chat <id>]

Clear active custom emoji status badge.

-C, --chat <id>

Target boosted channel or supergroup chat ID.

File Download Engine

grm file get [-A|–all] [-o|–output <dir|file>] [-t|–topic <id>] [-n|–limit <N>] [–type photo|video|doc|audio|all] <chat_id> [<message_ids…>]

Download specific attachment files by message ID, or bulk download all media files when -A or --all is specified.

-A, --all

Bulk download all attachment files in chat or topic.

-o, --output <dir|file>

Destination directory path or target file path.

-t, --topic <id>

Target specific forum topic ID.

-n, --limit <N>

Maximum messages to scan during bulk download (default: 100).

--type <type>

Filter media type: photo, video, doc, audio, or all.

Chat Folder Management

grm folder ls [-v|–verbose]

List all custom chat folders with included and excluded chat counts.

-v, --verbose

Display detailed folder metadata including full chat ID lists.

grm folder create [-g|–include-groups] [-c|–include-channels] [-b|–include-bots] [-C|–include-contacts] [-N|–include-non-contacts] [–exclude-muted] [–exclude-read] [–exclude-archived] [-i|–include-chats <chat_ids>] [-p|–pinned-chats <chat_ids>] “<title>”

Create a new chat folder.

-g, --include-groups

Include group and supergroup chats.

-c, --include-channels

Include broadcast channels.

-b, --include-bots

Include bot conversations.

-C, --include-contacts

Include contact conversations.

-N, --include-non-contacts

Include non-contact conversations.

--exclude-muted

Exclude muted chats.

--exclude-read

Exclude read chats.

--exclude-archived

Exclude archived chats.

-i, --include-chats <chat_ids>

Specific chat IDs to include (comma-separated or repeatable).

-p, --pinned-chats <chat_ids>

Specific chat IDs to pin in the folder (comma-separated or repeatable).

grm folder edit [-t|–title “<name>”] [-a|–add-chat <chat_id>] [-r|–remove-chat <chat_id>] [-P|–pin-chat <chat_id>] [-U|–unpin-chat <chat_id>] <folder_id>

Edit an existing chat folder configuration.

-t, –title “<name>”

New display title for the folder.

-a, --add-chat <chat_id>

Add chat ID to folder included list (repeatable).

-r, --remove-chat <chat_id>

Remove chat ID from folder included list (repeatable).

-P, --pin-chat <chat_id>

Pin chat ID in folder (repeatable).

-U, --unpin-chat <chat_id>

Unpin chat ID from folder (repeatable).

grm folder delete <folder_id>

Delete a chat folder by its numeric identifier.

Universal Cross-Domain Search

grm search <query> [-n|–limit <count>] [-o|–offset <count>] [-v|–verbose]

Execute an aggregated multi-domain search across chats, users, messages, and files.

-n, --limit <count>

Maximum search results per domain category (default: 20).

-o, --offset <count>

Offset starting result index (default: 0).

-v, --verbose

Display verbose entity metadata.

grm search chats <query> [-n|–limit <count>] [-o|–offset <count>] [-v|–verbose]

Search public and private chats, supergroups, and broadcast channels.

grm search supergroups <query> [-n|–limit <count>] [-o|–offset <count>] [-v|–verbose]

Search supergroups specifically, including forum supergroups.

grm search channels <query> [-n|–limit <count>] [-o|–offset <count>] [-v|–verbose]

Search broadcast channels specifically.

grm search msgs <query> [-c|–chat <chat_id>] [-n|–limit <count>] [-o|–offset <count>] [-v|–verbose]

Search message history globally across all chats or scoped to a specific chat.

-c, --chat <chat_id>

Restrict message search to target chat ID.

grm search users <query> [-n|–limit <count>] [-o|–offset <count>] [-v|–verbose]

Search contacts, direct messages, and public user profiles.

grm search files <query> [-t|–type <doc|photo|video|audio|all>] [-n|–limit <count>] [-o|–offset <count>] [-v|–verbose]

Search file attachments and media across chats.

-t, --type <type>

Filter attachment type: doc, photo, video, audio, or all (default: doc).

Shell Autocompletion

grm completion bash

Generate dynamic, context-aware shell autocompletion rules for Bash.

grm completion zsh

Generate native completion function script for Zsh.

grm completion fish

Generate completion definitions for Fish shell.

Examples

1. List active chats in table format:

   grm chat ls
   

2. Create a new forum topic with custom emoji icon in supergroup:

   grm topic create -e 5368560552786271734 -1003750297693 "DevOps Operations"
   

3. Send document attachment to topic:

   grm msg send -t 2 -a /var/log/syslog -C "System logs" -1003750297693
   

4. Bulk download all photos from topic:

   grm file get -A -o ~/Downloads -t 2 --type photo -1003750297693
   

5. Publish a Telegram Story with clickable URL and pin to profile page:

   grm story post --photo assets/logo.png --caption "grm ya soporta historias 🚀 https://gitlab.com/renich/grm" --pinned --period 24h
   

6. Edit an existing story’s caption and media:

   grm story edit --story-id 32 --caption "Updated caption with link: https://gitlab.com/renich/grm"
   

7. List active, profile, and archived stories:

   grm story ls --all
   

8. Search and set a 3D animated emoji status badge for 8 hours:

   # Search for laptop emojis across installed packs
   grm status ls 💻
   
   # Set 3D Animated Laptop badge for 8 hours
   grm status set --emoji 5431376038628171216 --duration 8h
   

9. Forward messages or media albums to another chat or forum topic:

   # Forward message 42 from source chat to target chat
   grm msg forward --from -100123456789 -100987654321 42
   
   # Forward as a copy without original forward header into forum topic 5
   grm msg forward -c -t 5 -100123456789 -100987654321 42 43 44
   

Planned Features & Architectural Roadmap

The following feature specifications define the planned functional roadmap for grm:

Contact Management

Complete management for Telegram contact lists and user profiles:

• grm contact ls: List all saved Telegram contacts and their online availability status via getContacts.

• grm contact info <user_id|phone|handle>: Inspect user profile details, bio, phone number, and restrictions via getUser and getUserFullInfo.

• grm contact add <phone> <first_name> [last_name] [--share-phone]: Import or add a new user to contacts via addContact and importContacts.

• grm contact delete <user_id>: Remove user from contacts list via removeContacts.

Silent & Scheduled Messages

Advanced message delivery controls utilizing TDLib’s messageSendOptions:

• grm msg send <chat_id> "<message>" [--silent] [--schedule-at "<datetime|duration>"] [--send-when-online]:

  • --silent/-s: Delivers the message silently without triggering sound or vibration notifications (disable_notification: true).

  • --schedule-at "<datetime|duration>": Schedules delivery at a specific date/time or relative duration via messageSchedulingStateSendAtDate.

  • --send-when-online: Delivers private chat messages automatically when the recipient comes online via messageSchedulingStateSendWhenOnline.

• grm msg scheduled ls <chat_id>: View pending scheduled messages in a chat or topic thread.

• grm msg scheduled delete <chat_id> <message_id>: Cancel and delete a pending scheduled message.

Audio & Voice Note Engine

First-class audio transmission and voice note processing:

• grm audio send <chat_id> <file_path> [--title "<title>"] [--performer "<performer>"] [--silent]: Send audio files with metadata via inputMessageAudio.

• grm audio voice <chat_id> <voice_ogg_path> [--convert] [--silent]: Send voice notes (OGG/Opus format) via inputMessageVoiceNote.

• grm audio info <file_path>: Inspect audio duration, sample rate, channels, and codec details via libsox.

Project Roadmap & Status

The following features and specifications have been implemented and verified:

• [x] Single-Source Command Registry: Unified CommandRegistry powering --help and grm completion.

• [x] Introspective Shell Completion: Native grm completion <bash|zsh|fish> engine with dynamic loader wrapper script.

• [x] GNU Standard Makefile: Default PREFIX ?= /usr/local with PREFIX_USER ?= $(HOME)/.local for non-root make install-local and make install-user.

• [x] File Engine Consolidation: Unified grm file get [-A|--all] <chat_id> [<message_ids...>] syntax.

• [x] Message Pin & Unpin: Consolidated grm msg pin, grm msg unpin, and grm msg unpin-all.

• [x] Chat Folder Management: Full CRUD via grm folder ls|create|edit|delete.

• [x] Universal Cross-Domain Search: Multi-domain search via grm search [chats|supergroups|channels|msgs|users|files].

• [x] Story & Emoji Status Management: Full lifecycle support via grm story and grm status.

Environment Variables

GRM_FORMAT

Set default output format: human, markdown, json, jsonl (or ndjson), or plain.

GRM_COLOR

Set default ANSI color mode: auto, always, or never.

NO_COLOR

Disables ANSI color output when present and non-empty.

Git Pre-Push Hook Setup

To register the repository pre-push quality automation hook (runs crstlint, make doc-check, make format, make check, and make lint prior to pushing to remote repositories):

make install-hooks

Installation & Setup

User/Build Dependencies

grm requires the following build toolchain and C++ libraries:

• tdlib-devel (>= 1.8.20): Telegram C++ JSON interface library (libtdjson)

• json-c-devel (>= 0.15): JSON parser and serialization engine

• cmake (>= 3.25): Build system generator

• ninja-build (>= 1.10): Fast build execution engine

• gcc-c++/clang: C++23 compiler suite

• python3-docutils: reStructuredText man page compiler (rst2man)

Developer Toolchain Dependencies

Contributors running static analysis or documentation validation also require:

• clang-tools-extra (>= 16.0): clang-tidy static analyzer and clang-format

• rstcheck (>= 6.0): reStructuredText syntax validator

Local User Installation

Per FHS 3.0 and the XDG Base Directory Specification, install grm into your user profile without root privileges (defaults to PREFIX_USER ?= ~/.local):

# Installs binary to ~/.local/bin/grm, man page to ~/.local/share/man/man1/grm.1, and completion wrapper
make install-local

# Ensure ~/.local/bin is present in your PATH:
export PATH="$HOME/.local/bin:$PATH"

System Installation

Per GNU Coding Standards Section 7.2.5, system installation defaults to PREFIX ?= /usr/local:

make release && sudo make install

Files & Configuration

~/.config/grm/config.json

User configuration file containing API credentials (api_id, api_hash) and output format defaults.

~/.local/lib/grm/tdlib_db/

Persistent TDLib database directory containing encrypted session state, authorization keys, and cache.

~/.local/bin/grm

User executable installation path per FHS 3.0.

~/.local/share/man/man1/grm.1

User manual page installation path.

~/.local/share/bash-completion/completions/grm

User Bash tab autocompletion dynamic wrapper script.

See Also

rst2man(1), sphinx-build(1), tdlib(7)