Introduction

Cligram is a Telegram client written with a Bun/JavaScript backend and a Go client.

• Currently supports chatting with personal chats, channels, and has beta support for bots.
• Lightweight, minimalistic, and terminal-based for basic messaging tasks.
• Not intended to replace GUI Telegram clients—some advanced features are missing.

Limitations

• Bot Interaction: Supported (beta).
• Media Management: No advanced media viewing/editing.
• Voice/Video Calls: Not supported.
• Rich Media Previews: Not displayed.
• Group Support: Supported, but you can only write in group chats. You cannot see the full member list.
• Multi-Account Support: Only one account at a time.

For a complete Telegram experience, use the official desktop or mobile apps.

Installation

1. Download or Build cligram

• Pre-built binaries: Download from releases page (Linux, macOS).
• Build from source: See this guide for instructions.
• Windows Support: While not officially supported, you can try running cligram using Windows Subsystem for Linux (WSL).

2. Using Docker

docker run --rm -it -v cligram_data:/root/.cligram \
  kumneger/cligram:latest

This persists your session.

Note on File Attachments: When using Docker, cligram runs in an isolated environment and cannot directly access files from your host machine. To attach a file, you first need to copy it into the running Docker container using the docker cp command. For example:

docker cp /path/to/your/file.jpg <container_id>:/root/

Once the file is copied, you can then attach it from within cligram.

Usage

Quick Start

• Login: Run cligram login and follow the prompts.
• Logout: Run cligram logout.
• Upgrade: On Debian/Ubuntu/Alpine, run cligram upgrade.

Layout

• Sidebar: Your chats list (Users, Groups, Channels).
• Chat Area: Messages of the selected chat.
• Focus: The active area has a green border. Use Tab to switch.

Indicators

• ● Online Status: A yellow icon before a user's name indicates they are online.
• ● Unread Messages: A red icon followed by a number in brackets (e.g., (3)) indicates the number of unread messages in a chat.

Navigation & Shortcuts

• Focus: Tab toggles focus between sidebar and chat.
• Move: ↑ / k moves up; ↓ / j moves down.
• Latest Message: Shift + ↓ gets the latest message (only in MainView).
• Filter (sidebar): c = Channels, g = Groups, u = Users.
• Search: ctrl + k opens search. Type to search; results appear below. Tab switches between input and results. Enter opens selection; Esc closes.

Working in Chats

• Select messages by moving with ↑/↓ (or k/j) in the chat area.
• d: delete • r: reply • e: edit • f: forward • u: DM the sender (from a group)

Compose & Attachments

• ctrl + a: Toggle the file picker when the input is focused.
• After picking a file, optionally add a caption, then press Enter to send. You may need to press Tab to focus on the input box after selecting the file.
• You will see a text indicating that the file is being uploaded.

Reading Behavior

• Typing indicator: If enabled, others see “typing…” while you compose.
• Read receipts (chat.readReceiptMode):
  • default: Mark read only when you interact (e.g., reply).
  • instant: Mark read as soon as you view.
  • never: Never mark read automatically.

Configuration

Customize your cligram experience by editing the config file at ~/.cligram/user.config.json.

Example Configuration

{
  "chat": {
    "sendTypingState": true,
    "readReceiptMode": "default"
  },
  "privacy": {
    "lastSeenVisibility": "everyone"
  },
  "notifications": {
    "enabled": true,
    "showMessagePreview": true
  }
}

Options

• chat.sendTypingState: Show "typing..." status (true = default, false = never show).
• chat.readReceiptMode:
  • "default": Marks as read only when you interact (default).
  • "instant": Marks as read when you view messages.
  • "never": Never automatically marks as read.
• privacy.lastSeenVisibility:
  • "everyone": Anyone can see your last seen time.
  • "contacts": Only contacts can see your last seen.
  • "nobody": No one can see your last seen.
  • If not set: Uses your Telegram privacy settings.
• notifications.enabled: Master switch for notifications (true = default, false = disable all).
• notifications.showMessagePreview: Show message content in notifications (true = default, false = only sender name).

All settings are optional. Changes take effect the next time you start cligram.

Troubleshooting

• File picker does not open: Make sure the message input is focused, then press ctrl + a again. Update to the latest version if it persists.
• Messages not marked read: Set chat.readReceiptMode to instant.
• Others cannot see typing: Set chat.sendTypingState to true.
• Where is data stored: App data and session live under ~/.cligram/.

Contributing

We welcome contributions to cligram! To get started:

• Read the CONTRIBUTING.md file for detailed guidelines.
• If you encounter issues or have suggestions, open an issue on GitHub.

Thank you for your interest in improving cligram!

FAQ

What platforms are supported?

cligram provides pre-built binaries for Linux and macOS. Windows is not officially supported, but you can try running cligram using Windows Subsystem for Linux (WSL).

Can I use multiple Telegram accounts?

No, only a single Telegram account is supported at a time.

Does cligram support bots, groups, or media management?

Bot interaction is now supported (beta). Group chat is supported for writing messages, but you cannot view the full member list. Advanced media features are not yet implemented, but are planned for future releases.

Where is my session data stored?

Session data is stored in ~/.cligram/ on your system. If using Docker, a volume is used to persist this data.

How do I update cligram?

Download the latest release from the releases page or rebuild from source. If you are on Debian, Ubuntu, or Alpine Linux, you can upgrade to the latest version using cligram upgrade.

License

This project is licensed under the MIT License. See the LICENSE file for details.