codex-tgmember 1.0.0__tar.gz

codex_tgmember-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 K.NIRMAL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

codex_tgmember-1.0.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: codex-tgmember
+Version: 1.0.0
+Summary: A CLI tool to scrape and add members in Telegram groups using the Telethon library.
+Author: K.NIRMAL
+License: MIT
+Project-URL: Homepage, https://github.com/kAWDHITHA-NIRMAL/codex-tgmember
+Project-URL: Bug Tracker, https://github.com/kAWDHITHA-NIRMAL/codex-tgmember/issues
+Keywords: telegram,scraper,members,telethon,group
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Utilities
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: telethon>=1.34.0
+Dynamic: license-file
+
+# codex-tgmember 🔭
+
+> **⚠️ For educational purposes only. Use responsibly and in compliance with [Telegram's Terms of Service](https://telegram.org/tos).**
+
+A Python package to **scrape members** from Telegram groups and **add them** to your own group — powered by [Telethon](https://docs.telethon.dev/).
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---|---|
+| 📋 **Scrape Members** | Export all visible group members to a CSV file |
+| ➕ **Add Members** | Bulk-add users from CSV by username or Telegram ID |
+| 📂 **CSV Viewer** | Display any member CSV file in the terminal |
+| 🔐 **2FA Support** | Handles two-step verification automatically |
+| 🛡️ **Safe Fallback** | Falls back gracefully when admin rights are missing |
+
+---
+
+## 📦 Installation
+
+### From PyPI *(after publishing)*
+```bash
+pip install codex-tgmember
+```
+
+### From source (local)
+```bash
+cd pack/
+pip install .
+```
+
+---
+
+## 🔑 Prerequisites
+
+1. **Python 3.7+**
+2. A **Telegram account** with a phone number
+3. **API credentials** from [my.telegram.org](https://my.telegram.org):
+   - Go to **API development tools**
+   - Create an app → copy `api_id` and `api_hash`
+
+---
+
+## ⚙️ Configuration
+
+### Option A — Use as a Python library
+
+```python
+from tg_member_tool import TelegramMemberTool
+
+tool = TelegramMemberTool(
+    api_id=12345678,           # your API ID
+    api_hash='your_api_hash',  # your API Hash
+    phone='+94707728716'       # your phone with country code
+)
+
+# Start interactive menu
+tool.run()
+```
+
+### Option B — Edit `cli.py` and use the command line
+
+Open `pack/tg_member_tool/cli.py` and fill in your credentials:
+
+```python
+API_ID   = 12345678
+API_HASH = 'your_api_hash_here'
+PHONE    = '+94707728716'
+```
+
+Then run:
+
+```bash
+tg-member-tool
+```
+
+---
+
+## 🚀 Usage
+
+### Interactive Menu
+
+```
+╔══════════════════════════════╗
+║     Telegram Member Tool     ║
+╚══════════════════════════════╝
+
+  1. Scrape group members → CSV
+  2. Add members from CSV
+  3. Display CSV file
+
+  Select option:
+```
+
+---
+
+### 1️⃣ Scrape Members → CSV
+
+```python
+tool.scrape_members()
+# or pass index directly (no prompt):
+tool.scrape_members(group_index=5)
+```
+
+Output file: `members-groupname.csv`
+
+```
+username,user_id,access_hash,name,group,group_id
+john_doe,123456789,9876543210987654321,John Doe,My Group,1001234567
+```
+
+---
+
+### 2️⃣ Add Members from CSV
+
+```python
+tool.add_members('members-my-group.csv')
+# or specify group and method directly:
+tool.add_members('members.csv', group_index=2, method=1)
+```
+
+**CSV format required:**
+```csv
+username,user_id,access_hash
+john_doe,123456789,9876543210987654321
+jane_doe,987654321,1234567890123456789
+```
+
+**Add methods:**
+- `1` — by **username** (more reliable, requires user to have a username)
+- `2` — by **Telegram ID** (works even without a username)
+
+---
+
+### 3️⃣ Display CSV File
+
+```python
+tool.display_csv('members-my-group.csv')
+```
+
+---
+
+## 📁 Package Structure
+
+```
+pack/
+├── pyproject.toml              ← Package config & metadata
+├── LICENSE
+├── README.md
+└── tg_member_tool/
+    ├── __init__.py             ← Package entry, exports TelegramMemberTool
+    ├── core.py                 ← Main TelegramMemberTool class
+    └── cli.py                  ← `tg-member-tool` command entry point
+```
+
+---
+
+## ⚠️ Common Errors & Fixes
+
+| Error | Cause | Fix |
+|---|---|---|
+| `SessionPasswordNeededError` | 2FA is enabled | Enter your 2FA password when prompted |
+| `ChatAdminRequiredError` | Not admin of the group | Choose a group where you are admin |
+| `PeerFloodError` | Too many requests | Wait several hours before trying again |
+| `UserPrivacyRestrictedError` | User has privacy on | User is skipped automatically |
+| `AuthRestartError` | Telegram internal issue | Re-run the script |
+
+---
+
+## 🔐 Security Notes
+
+- 🔑 **Never share** your `api_id`, `api_hash`, or `.session` file
+- ❌ **Never commit** credentials to GitHub — add them to `.gitignore`
+- ⏳ Respect Telegram's rate limits: [limits.tginfo.me](https://limits.tginfo.me/en)
+- 👥 Only add users who have **consented** to join groups
+
+---
+
+## 📜 Disclaimer
+
+This tool is provided **for educational purposes only**. The author is not responsible for:
+- Account bans due to aggressive API use
+- Privacy violations or spam complaints  
+- Any misuse of this software
+
+Always comply with [Telegram's Terms of Service](https://telegram.org/tos).
+
+---
+
+## 📄 License
+
+MIT © K.NIRMAL

codex_tgmember-1.0.0/README.md

@@ -0,0 +1,194 @@
+# codex-tgmember 🔭
+
+> **⚠️ For educational purposes only. Use responsibly and in compliance with [Telegram's Terms of Service](https://telegram.org/tos).**
+
+A Python package to **scrape members** from Telegram groups and **add them** to your own group — powered by [Telethon](https://docs.telethon.dev/).
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---|---|
+| 📋 **Scrape Members** | Export all visible group members to a CSV file |
+| ➕ **Add Members** | Bulk-add users from CSV by username or Telegram ID |
+| 📂 **CSV Viewer** | Display any member CSV file in the terminal |
+| 🔐 **2FA Support** | Handles two-step verification automatically |
+| 🛡️ **Safe Fallback** | Falls back gracefully when admin rights are missing |
+
+---
+
+## 📦 Installation
+
+### From PyPI *(after publishing)*
+```bash
+pip install codex-tgmember
+```
+
+### From source (local)
+```bash
+cd pack/
+pip install .
+```
+
+---
+
+## 🔑 Prerequisites
+
+1. **Python 3.7+**
+2. A **Telegram account** with a phone number
+3. **API credentials** from [my.telegram.org](https://my.telegram.org):
+   - Go to **API development tools**
+   - Create an app → copy `api_id` and `api_hash`
+
+---
+
+## ⚙️ Configuration
+
+### Option A — Use as a Python library
+
+```python
+from tg_member_tool import TelegramMemberTool
+
+tool = TelegramMemberTool(
+    api_id=12345678,           # your API ID
+    api_hash='your_api_hash',  # your API Hash
+    phone='+94707728716'       # your phone with country code
+)
+
+# Start interactive menu
+tool.run()
+```
+
+### Option B — Edit `cli.py` and use the command line
+
+Open `pack/tg_member_tool/cli.py` and fill in your credentials:
+
+```python
+API_ID   = 12345678
+API_HASH = 'your_api_hash_here'
+PHONE    = '+94707728716'
+```
+
+Then run:
+
+```bash
+tg-member-tool
+```
+
+---
+
+## 🚀 Usage
+
+### Interactive Menu
+
+```
+╔══════════════════════════════╗
+║     Telegram Member Tool     ║
+╚══════════════════════════════╝
+
+  1. Scrape group members → CSV
+  2. Add members from CSV
+  3. Display CSV file
+
+  Select option:
+```
+
+---
+
+### 1️⃣ Scrape Members → CSV
+
+```python
+tool.scrape_members()
+# or pass index directly (no prompt):
+tool.scrape_members(group_index=5)
+```
+
+Output file: `members-groupname.csv`
+
+```
+username,user_id,access_hash,name,group,group_id
+john_doe,123456789,9876543210987654321,John Doe,My Group,1001234567
+```
+
+---
+
+### 2️⃣ Add Members from CSV
+
+```python
+tool.add_members('members-my-group.csv')
+# or specify group and method directly:
+tool.add_members('members.csv', group_index=2, method=1)
+```
+
+**CSV format required:**
+```csv
+username,user_id,access_hash
+john_doe,123456789,9876543210987654321
+jane_doe,987654321,1234567890123456789
+```
+
+**Add methods:**
+- `1` — by **username** (more reliable, requires user to have a username)
+- `2` — by **Telegram ID** (works even without a username)
+
+---
+
+### 3️⃣ Display CSV File
+
+```python
+tool.display_csv('members-my-group.csv')
+```
+
+---
+
+## 📁 Package Structure
+
+```
+pack/
+├── pyproject.toml              ← Package config & metadata
+├── LICENSE
+├── README.md
+└── tg_member_tool/
+    ├── __init__.py             ← Package entry, exports TelegramMemberTool
+    ├── core.py                 ← Main TelegramMemberTool class
+    └── cli.py                  ← `tg-member-tool` command entry point
+```
+
+---
+
+## ⚠️ Common Errors & Fixes
+
+| Error | Cause | Fix |
+|---|---|---|
+| `SessionPasswordNeededError` | 2FA is enabled | Enter your 2FA password when prompted |
+| `ChatAdminRequiredError` | Not admin of the group | Choose a group where you are admin |
+| `PeerFloodError` | Too many requests | Wait several hours before trying again |
+| `UserPrivacyRestrictedError` | User has privacy on | User is skipped automatically |
+| `AuthRestartError` | Telegram internal issue | Re-run the script |
+
+---
+
+## 🔐 Security Notes
+
+- 🔑 **Never share** your `api_id`, `api_hash`, or `.session` file
+- ❌ **Never commit** credentials to GitHub — add them to `.gitignore`
+- ⏳ Respect Telegram's rate limits: [limits.tginfo.me](https://limits.tginfo.me/en)
+- 👥 Only add users who have **consented** to join groups
+
+---
+
+## 📜 Disclaimer
+
+This tool is provided **for educational purposes only**. The author is not responsible for:
+- Account bans due to aggressive API use
+- Privacy violations or spam complaints  
+- Any misuse of this software
+
+Always comply with [Telegram's Terms of Service](https://telegram.org/tos).
+
+---
+
+## 📄 License
+
+MIT © K.NIRMAL

codex_tgmember-1.0.0/codex_tgmember.egg-info/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: codex-tgmember
+Version: 1.0.0
+Summary: A CLI tool to scrape and add members in Telegram groups using the Telethon library.
+Author: K.NIRMAL
+License: MIT
+Project-URL: Homepage, https://github.com/kAWDHITHA-NIRMAL/codex-tgmember
+Project-URL: Bug Tracker, https://github.com/kAWDHITHA-NIRMAL/codex-tgmember/issues
+Keywords: telegram,scraper,members,telethon,group
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Utilities
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: telethon>=1.34.0
+Dynamic: license-file
+
+# codex-tgmember 🔭
+
+> **⚠️ For educational purposes only. Use responsibly and in compliance with [Telegram's Terms of Service](https://telegram.org/tos).**
+
+A Python package to **scrape members** from Telegram groups and **add them** to your own group — powered by [Telethon](https://docs.telethon.dev/).
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---|---|
+| 📋 **Scrape Members** | Export all visible group members to a CSV file |
+| ➕ **Add Members** | Bulk-add users from CSV by username or Telegram ID |
+| 📂 **CSV Viewer** | Display any member CSV file in the terminal |
+| 🔐 **2FA Support** | Handles two-step verification automatically |
+| 🛡️ **Safe Fallback** | Falls back gracefully when admin rights are missing |
+
+---
+
+## 📦 Installation
+
+### From PyPI *(after publishing)*
+```bash
+pip install codex-tgmember
+```
+
+### From source (local)
+```bash
+cd pack/
+pip install .
+```
+
+---
+
+## 🔑 Prerequisites
+
+1. **Python 3.7+**
+2. A **Telegram account** with a phone number
+3. **API credentials** from [my.telegram.org](https://my.telegram.org):
+   - Go to **API development tools**
+   - Create an app → copy `api_id` and `api_hash`
+
+---
+
+## ⚙️ Configuration
+
+### Option A — Use as a Python library
+
+```python
+from tg_member_tool import TelegramMemberTool
+
+tool = TelegramMemberTool(
+    api_id=12345678,           # your API ID
+    api_hash='your_api_hash',  # your API Hash
+    phone='+94707728716'       # your phone with country code
+)
+
+# Start interactive menu
+tool.run()
+```
+
+### Option B — Edit `cli.py` and use the command line
+
+Open `pack/tg_member_tool/cli.py` and fill in your credentials:
+
+```python
+API_ID   = 12345678
+API_HASH = 'your_api_hash_here'
+PHONE    = '+94707728716'
+```
+
+Then run:
+
+```bash
+tg-member-tool
+```
+
+---
+
+## 🚀 Usage
+
+### Interactive Menu
+
+```
+╔══════════════════════════════╗
+║     Telegram Member Tool     ║
+╚══════════════════════════════╝
+
+  1. Scrape group members → CSV
+  2. Add members from CSV
+  3. Display CSV file
+
+  Select option:
+```
+
+---
+
+### 1️⃣ Scrape Members → CSV
+
+```python
+tool.scrape_members()
+# or pass index directly (no prompt):
+tool.scrape_members(group_index=5)
+```
+
+Output file: `members-groupname.csv`
+
+```
+username,user_id,access_hash,name,group,group_id
+john_doe,123456789,9876543210987654321,John Doe,My Group,1001234567
+```
+
+---
+
+### 2️⃣ Add Members from CSV
+
+```python
+tool.add_members('members-my-group.csv')
+# or specify group and method directly:
+tool.add_members('members.csv', group_index=2, method=1)
+```
+
+**CSV format required:**
+```csv
+username,user_id,access_hash
+john_doe,123456789,9876543210987654321
+jane_doe,987654321,1234567890123456789
+```
+
+**Add methods:**
+- `1` — by **username** (more reliable, requires user to have a username)
+- `2` — by **Telegram ID** (works even without a username)
+
+---
+
+### 3️⃣ Display CSV File
+
+```python
+tool.display_csv('members-my-group.csv')
+```
+
+---
+
+## 📁 Package Structure
+
+```
+pack/
+├── pyproject.toml              ← Package config & metadata
+├── LICENSE
+├── README.md
+└── tg_member_tool/
+    ├── __init__.py             ← Package entry, exports TelegramMemberTool
+    ├── core.py                 ← Main TelegramMemberTool class
+    └── cli.py                  ← `tg-member-tool` command entry point
+```
+
+---
+
+## ⚠️ Common Errors & Fixes
+
+| Error | Cause | Fix |
+|---|---|---|
+| `SessionPasswordNeededError` | 2FA is enabled | Enter your 2FA password when prompted |
+| `ChatAdminRequiredError` | Not admin of the group | Choose a group where you are admin |
+| `PeerFloodError` | Too many requests | Wait several hours before trying again |
+| `UserPrivacyRestrictedError` | User has privacy on | User is skipped automatically |
+| `AuthRestartError` | Telegram internal issue | Re-run the script |
+
+---
+
+## 🔐 Security Notes
+
+- 🔑 **Never share** your `api_id`, `api_hash`, or `.session` file
+- ❌ **Never commit** credentials to GitHub — add them to `.gitignore`
+- ⏳ Respect Telegram's rate limits: [limits.tginfo.me](https://limits.tginfo.me/en)
+- 👥 Only add users who have **consented** to join groups
+
+---
+
+## 📜 Disclaimer
+
+This tool is provided **for educational purposes only**. The author is not responsible for:
+- Account bans due to aggressive API use
+- Privacy violations or spam complaints  
+- Any misuse of this software
+
+Always comply with [Telegram's Terms of Service](https://telegram.org/tos).
+
+---
+
+## 📄 License
+
+MIT © K.NIRMAL

codex_tgmember-1.0.0/codex_tgmember.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+codex_tgmember.egg-info/PKG-INFO
+codex_tgmember.egg-info/SOURCES.txt
+codex_tgmember.egg-info/dependency_links.txt
+codex_tgmember.egg-info/entry_points.txt
+codex_tgmember.egg-info/requires.txt
+codex_tgmember.egg-info/top_level.txt
+tg_member_tool/__init__.py
+tg_member_tool/cli.py
+tg_member_tool/core.py

codex_tgmember-1.0.0/codex_tgmember.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

codex_tgmember-1.0.0/codex_tgmember.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-tgmember = tg_member_tool.cli:main

codex_tgmember-1.0.0/codex_tgmember.egg-info/requires.txt

@@ -0,0 +1 @@
+telethon>=1.34.0

codex_tgmember-1.0.0/codex_tgmember.egg-info/top_level.txt

@@ -0,0 +1 @@
+tg_member_tool

codex_tgmember-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codex-tgmember"
+version = "1.0.0"
+description = "A CLI tool to scrape and add members in Telegram groups using the Telethon library."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "K.NIRMAL" }
+]
+keywords = ["telegram", "scraper", "members", "telethon", "group"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Communications :: Chat",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.7"
+dependencies = [
+    "telethon>=1.34.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/kAWDHITHA-NIRMAL/codex-tgmember"
+"Bug Tracker" = "https://github.com/kAWDHITHA-NIRMAL/codex-tgmember/issues"
+
+[project.scripts]
+codex-tgmember = "tg_member_tool.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tg_member_tool*"]

codex_tgmember-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codex_tgmember-1.0.0/tg_member_tool/__init__.py

@@ -0,0 +1,11 @@
+"""
+tg_member_tool - Telegram Group Member Scraper & Adder
+"""
+
+__version__ = "1.0.0"
+__author__ = "K.NIRMAL"
+__license__ = "MIT"
+
+from .core import TelegramMemberTool
+
+__all__ = ["TelegramMemberTool"]

codex_tgmember-1.0.0/tg_member_tool/cli.py

@@ -0,0 +1,26 @@
+"""
+cli.py - Command-line entry point for tg-member-tool
+"""
+
+import sys
+from tg_member_tool import TelegramMemberTool
+
+
+def main():
+    """Entry point invoked by `tg-member-tool` command after pip install."""
+
+    # These must be set by the user before using the package
+    API_ID   = 0                  # ← Replace with your API ID
+    API_HASH = 'your_api_hash'    # ← Replace with your API Hash
+    PHONE    = '+your_phone'      # ← Replace with your phone number
+
+    if API_ID == 0 or API_HASH == 'your_api_hash':
+        print('❌ Please set your API_ID, API_HASH, and PHONE in cli.py before running.')
+        sys.exit(1)
+
+    tool = TelegramMemberTool(api_id=API_ID, api_hash=API_HASH, phone=PHONE)
+    tool.run()
+
+
+if __name__ == '__main__':
+    main()

codex_tgmember-1.0.0/tg_member_tool/core.py

@@ -0,0 +1,265 @@
+"""
+core.py - Main logic for TelegramMemberTool
+"""
+
+import csv
+import re
+import sys
+import time
+import traceback
+
+from telethon.sync import TelegramClient
+from telethon.tl.functions.channels import InviteToChannelRequest
+from telethon.tl.functions.messages import GetDialogsRequest
+from telethon.tl.types import InputPeerChannel, InputPeerEmpty, InputPeerUser
+from telethon.errors.rpcerrorlist import PeerFloodError, UserPrivacyRestrictedError
+
+
+class TelegramMemberTool:
+    """
+    A tool to scrape and add members in Telegram groups.
+
+    Args:
+        api_id (int): Your Telegram API ID from https://my.telegram.org
+        api_hash (str): Your Telegram API Hash from https://my.telegram.org
+        phone (str): Your phone number with country code (e.g. '+94707728716')
+
+    Example::
+
+        from tg_member_tool import TelegramMemberTool
+
+        tool = TelegramMemberTool(
+            api_id=12345678,
+            api_hash='your_api_hash_here',
+            phone='+94707728716'
+        )
+        tool.run()
+    """
+
+    def __init__(self, api_id: int, api_hash: str, phone: str):
+        self.phone = phone
+        self.client = TelegramClient(phone, api_id, api_hash)
+
+    # ------------------------------------------------------------------
+    # Authentication
+    # ------------------------------------------------------------------
+
+    def connect(self):
+        """Connect and authenticate. Handles SMS code and 2FA password."""
+        self.client.connect()
+        if not self.client.is_user_authorized():
+            self.client.send_code_request(self.phone)
+            try:
+                self.client.sign_in(self.phone, input('Enter verification code: '))
+            except Exception as e:
+                if 'SessionPasswordNeededError' in type(e).__name__:
+                    self.client.sign_in(
+                        password=input('2FA password required. Enter password: ')
+                    )
+                else:
+                    raise
+
+    # ------------------------------------------------------------------
+    # Core features
+    # ------------------------------------------------------------------
+
+    def list_chats(self):
+        """Return a list of all chats/groups the account is part of."""
+        result = self.client(GetDialogsRequest(
+            offset_date=None,
+            offset_id=0,
+            offset_peer=InputPeerEmpty(),
+            limit=200,
+            hash=0
+        ))
+        return result.chats
+
+    def scrape_members(self, group_index: int = None) -> str:
+        """
+        Scrape members from a group and save to CSV.
+
+        Args:
+            group_index (int, optional): Index of the group from the chats list.
+                                         If None, the user will be prompted.
+
+        Returns:
+            str: Path to the saved CSV file, or empty string on failure.
+        """
+        chats = self.list_chats()
+
+        if group_index is None:
+            print('\nAvailable chats:')
+            for idx, chat in enumerate(chats):
+                print(f'  {idx}: {chat.title}')
+            group_index = int(input('\nEnter group number: '))
+
+        target_group = chats[group_index]
+        print(f'\nFetching members from: {target_group.title}')
+
+        participants = self._fetch_participants(target_group)
+        if participants is None:
+            return ''
+
+        filename = self._save_to_csv(participants, target_group)
+        print(f'✅ Saved {len(participants)} members to {filename}')
+        return filename
+
+    def add_members(self, csv_file: str, group_index: int = None, method: int = None):
+        """
+        Add members from a CSV file to a group.
+
+        Args:
+            csv_file (str): Path to the CSV file (must have username, user_id, access_hash columns).
+            group_index (int, optional): Index of the target group. Prompts if None.
+            method (int, optional): 1 = by username, 2 = by ID. Prompts if None.
+        """
+        users = self._load_csv(csv_file)
+        if not users:
+            print('❌ No valid users found in CSV.')
+            return
+
+        result = self.client(GetDialogsRequest(
+            offset_date=None,
+            offset_id=0,
+            offset_peer=InputPeerEmpty(),
+            limit=200,
+            hash=0
+        ))
+        groups = [c for c in result.chats if getattr(c, 'megagroup', False)]
+
+        if group_index is None:
+            print('\nAvailable groups (supergroups only):')
+            for idx, g in enumerate(groups):
+                print(f'  {idx}: {g.title}')
+            group_index = int(input('\nEnter group number: '))
+
+        target_group = groups[group_index]
+        target_entity = InputPeerChannel(target_group.id, target_group.access_hash)
+
+        if method is None:
+            method = int(input('\nAdd method (1-by username, 2-by ID): '))
+
+        for user in users:
+            try:
+                print(f'Adding {user["username"] or user["id"]}...')
+                if method == 1:
+                    user_entity = self.client.get_input_entity(user['username'])
+                elif method == 2:
+                    user_entity = InputPeerUser(user['id'], user['access_hash'])
+                else:
+                    print('Invalid method. Use 1 or 2.')
+                    break
+
+                self.client(InviteToChannelRequest(target_entity, [user_entity]))
+                print('  ✅ Added. Waiting 60 seconds...')
+                time.sleep(60)
+
+            except PeerFloodError:
+                print('⚠️  Flood error — stopping to protect account. Try again later.')
+                break
+            except UserPrivacyRestrictedError:
+                print(f'  ⚠️  Privacy restricted. Skipping {user["username"]}.')
+            except Exception as e:
+                print(f'  ❌ Error: {e}')
+                traceback.print_exc()
+
+    def display_csv(self, csv_file: str):
+        """Print contents of a CSV file to terminal."""
+        with open(csv_file, encoding='UTF-8') as f:
+            reader = csv.reader(f, delimiter=',', lineterminator='\n')
+            for row in reader:
+                print(row)
+
+    # ------------------------------------------------------------------
+    # Interactive menu
+    # ------------------------------------------------------------------
+
+    def run(self):
+        """Start the interactive CLI menu."""
+        self.connect()
+
+        print('\n╔══════════════════════════════╗')
+        print('║     Telegram Member Tool     ║')
+        print('╚══════════════════════════════╝')
+
+        choice = int(input(
+            '\n  1. Scrape group members → CSV\n'
+            '  2. Add members from CSV\n'
+            '  3. Display CSV file\n'
+            '\n  Select option: '
+        ))
+
+        if choice == 1:
+            self.scrape_members()
+        elif choice == 2:
+            if len(sys.argv) < 2:
+                csv_file = input('Enter path to CSV file: ')
+            else:
+                csv_file = sys.argv[1]
+            self.add_members(csv_file)
+        elif choice == 3:
+            if len(sys.argv) < 2:
+                csv_file = input('Enter path to CSV file: ')
+            else:
+                csv_file = sys.argv[1]
+            self.display_csv(csv_file)
+        else:
+            print('Invalid selection.')
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _fetch_participants(self, target_group):
+        """Try aggressive fetch, fall back to standard. Returns None if both fail."""
+        try:
+            return self.client.get_participants(target_group, aggressive=True)
+        except Exception as e:
+            if 'ChatAdminRequiredError' not in type(e).__name__:
+                raise
+            print('  Aggressive fetch failed — trying standard fetch...')
+            try:
+                return self.client.get_participants(target_group)
+            except Exception as e2:
+                if 'ChatAdminRequiredError' in type(e2).__name__:
+                    print(f'\n❌ Cannot fetch members from "{target_group.title}".')
+                    print('   This group hides its member list from non-admins.')
+                    return None
+                raise
+
+    def _save_to_csv(self, participants, target_group) -> str:
+        """Save participants list to a CSV file and return the filename."""
+        sanitized = re.sub('[^a-z0-9]+', '-', target_group.title.lower()).strip('-')
+        filename = f'members-{sanitized}.csv'
+        with open(filename, 'w', encoding='UTF-8') as f:
+            writer = csv.writer(f, delimiter=',', lineterminator='\n')
+            writer.writerow(['username', 'user_id', 'access_hash', 'name', 'group', 'group_id'])
+            for user in participants:
+                name = ' '.join(filter(None, [user.first_name, user.last_name]))
+                writer.writerow([
+                    user.username or '',
+                    user.id,
+                    user.access_hash,
+                    name,
+                    target_group.title,
+                    target_group.id
+                ])
+        return filename
+
+    @staticmethod
+    def _load_csv(filepath: str) -> list:
+        """Load users from a CSV file. Returns list of dicts."""
+        users = []
+        with open(filepath, encoding='UTF-8') as f:
+            reader = csv.reader(f, delimiter=',', lineterminator='\n')
+            next(reader)  # skip header
+            for row in reader:
+                if len(row) < 3:
+                    print('  Skipping incomplete record.')
+                    continue
+                users.append({
+                    'username': row[0],
+                    'id': int(row[1]) if row[1] else 0,
+                    'access_hash': int(row[2]) if row[2] else 0,
+                })
+        return users