tg-mtproto-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cyberash
+
+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.

package/README.md

@@ -0,0 +1,90 @@
+# tg-mtproto-cli
+
+CLI for Telegram via MTProto. Direct access to chats, messages and media — no Bot API, no limits.
+
+## Features
+
+- **Multi-account** — manage multiple Telegram accounts with aliases
+- **Chats** — list dialogs with unread counters
+- **Messages** — fetch messages from any chat, group or supergroup
+- **Forum topics** — list and read topics in supergroup forums
+- **Media download** — download photos, videos, documents
+- **Time filter** — `--after` to show messages since a specific time
+- **JSON output** — `--json` flag for scripting and piping
+- **Secure storage** — credentials in system keychain (macOS Keychain, Windows Credential Vault, Linux Secret Service)
+
+## Prerequisites
+
+You need Telegram API credentials (`api_id` and `api_hash`).
+Get them at [my.telegram.org](https://my.telegram.org/apps).
+
+## Install
+
+```bash
+npm install -g tg-mtproto-cli
+```
+
+## Quick start
+
+```bash
+# Authenticate (will prompt for API credentials on first run)
+tg auth
+
+# List your chats
+tg chats
+
+# Last 20 messages from a chat
+tg messages @username -n 20
+
+# Messages since 9am today
+tg messages @username --after 09:00
+
+# Download a photo
+tg download @username 42
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `tg auth` | Authenticate a Telegram account |
+| `tg logout <alias>` | Log out and remove session |
+| `tg accounts` | List all accounts |
+| `tg accounts rename <old> <new>` | Rename an account alias |
+| `tg default <alias>` | Set the default account |
+| `tg chats` | List chats |
+| `tg messages <chat>` | List messages from a chat |
+| `tg topics <chat>` | List forum topics in a supergroup |
+| `tg download <chat> <messageId>` | Download media from a message |
+
+## Messages options
+
+```bash
+tg messages <chat> [options]
+```
+
+| Option | Description |
+|---|---|
+| `-n <count>` | Number of messages (default: 100) |
+| `--all` | Load entire chat history |
+| `--topic <id>` | Messages from a specific forum topic |
+| `--after <datetime>` | Messages after a given time |
+
+`--after` accepts: `2026-02-22`, `2026-02-22T10:00`, `10:00` (today).
+
+## Global flags
+
+| Flag | Description |
+|---|---|
+| `--account <alias>` | Use a specific account |
+| `--json` | Output in JSON format |
+
+## How it works
+
+Uses [mtcute](https://github.com/mtcute/mtcute) for MTProto protocol.
+Sessions are stored in `~/.tg-mtproto-cli/sessions/`.
+Credentials are stored in the system keychain via [cross-keychain](https://github.com/nicolo-ribaudo/cross-keychain).
+
+## License
+
+MIT

package/dist/main.mjs

@@ -0,0 +1,1142 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import Table from "cli-table3";
+import { createInterface } from "node:readline";
+import { Presets, SingleBar } from "cli-progress";
+import { deletePassword, getPassword, setPassword } from "cross-keychain";
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { TelegramClient } from "@mtcute/node";
+import { encodeQR } from "qr";
+
+//#region src/cli/formatters/account-formatter.ts
+function formatAccountsTable(accounts) {
+	if (accounts.length === 0) return chalk.yellow("No accounts found. Use 'tg auth' to log in.");
+	const table = new Table({
+		head: [
+			"#",
+			"Alias",
+			"Phone",
+			"Name",
+			"Default"
+		],
+		style: { head: ["cyan"] }
+	});
+	accounts.forEach((acc, i) => {
+		const name = acc.lastName ? `${acc.firstName} ${acc.lastName}` : acc.firstName;
+		table.push([
+			i + 1,
+			acc.alias,
+			acc.phone,
+			name,
+			acc.isDefault ? chalk.green("*") : ""
+		]);
+	});
+	return table.toString();
+}
+function formatAccountsJson(accounts) {
+	return JSON.stringify(accounts, null, 2);
+}
+
+//#endregion
+//#region src/cli/commands/accounts.ts
+function registerAccountsCommand(program, accountsListUseCase, accountsRenameUseCase) {
+	const accountsCmd = program.command("accounts").description("Manage accounts");
+	accountsCmd.command("list", { isDefault: true }).description("List all logged-in accounts").action(async () => {
+		try {
+			const accounts = await accountsListUseCase.execute();
+			const json = program.opts().json;
+			console.log(json ? formatAccountsJson(accounts) : formatAccountsTable(accounts));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error(chalk.red(message));
+			process.exit(1);
+		}
+	});
+	accountsCmd.command("rename <old> <new>").description("Rename an account alias").action(async (oldAlias, newAlias) => {
+		try {
+			await accountsRenameUseCase.execute(oldAlias, newAlias);
+			console.log(chalk.green(`Account alias renamed: "${oldAlias}" -> "${newAlias}"`));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error(chalk.red(message));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/auth.ts
+function prompt(rl, question, isPassword = false) {
+	return new Promise((resolve) => rl.question(question, (answer) => {
+		if (isPassword) resolve(answer);
+		else resolve(answer.trim());
+	}));
+}
+function registerAuthCommand(program, authUseCase) {
+	program.command("auth").description("Authorize a Telegram account").action(async () => {
+		const rl = createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		try {
+			const account = await authUseCase.execute({
+				promptApiId: async () => {
+					const raw = await prompt(rl, "API ID (from https://my.telegram.org): ");
+					const id = parseInt(raw, 10);
+					if (Number.isNaN(id)) throw new Error("Invalid API ID");
+					return id;
+				},
+				promptApiHash: async () => {
+					return prompt(rl, "API Hash: ");
+				},
+				promptPhone: async () => {
+					return prompt(rl, "Phone number: ");
+				},
+				promptCode: async () => {
+					return prompt(rl, "Confirmation code: ");
+				},
+				promptPassword: async () => {
+					return prompt(rl, "2FA password: ", true);
+				},
+				promptAlias: async (defaultAlias) => {
+					return (await prompt(rl, `Alias (default: ${defaultAlias}): `)).trim() || defaultAlias;
+				},
+				onAliasTaken: (alias) => {
+					console.error(chalk.red(`Alias "${alias}" is already taken. Choose another.`));
+				},
+				onAlreadyLoggedIn: async (existing) => {
+					return (await prompt(rl, chalk.yellow(`Account "${existing.alias}" (${existing.phone}) is already logged in. Re-authenticate? (y/n): `))).toLowerCase() === "y";
+				}
+			});
+			const name = account.lastName ? `${account.firstName} ${account.lastName}` : account.firstName;
+			const username = account.username ? ` (@${account.username})` : "";
+			console.log(chalk.green(`Logged in as ${name}${username}, alias: ${account.alias}`));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error(chalk.red(message));
+			process.exit(1);
+		} finally {
+			rl.close();
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/formatters/chat-formatter.ts
+function formatTimeAgo(date) {
+	const seconds = Math.floor((Date.now() - date.getTime()) / 1e3);
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes} min ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	return `${Math.floor(hours / 24)}d ago`;
+}
+function formatChatsTable(chats) {
+	if (chats.length === 0) return chalk.yellow("No chats found.");
+	const table = new Table({
+		head: [
+			"#",
+			"Chat ID",
+			"Type",
+			"Title",
+			"Unread",
+			"Last Activity"
+		],
+		style: { head: ["cyan"] }
+	});
+	chats.forEach((chat, i) => {
+		table.push([
+			i + 1,
+			chat.id,
+			chat.type,
+			chat.title,
+			chat.unreadCount > 0 ? chalk.bold(String(chat.unreadCount)) : "—",
+			formatTimeAgo(chat.lastActivity)
+		]);
+	});
+	return table.toString();
+}
+function formatChatsJson(chats) {
+	return JSON.stringify(chats, null, 2);
+}
+
+//#endregion
+//#region src/cli/commands/chats.ts
+const VALID_TYPES = [
+	"private",
+	"group",
+	"supergroup",
+	"channel"
+];
+function registerChatsCommand(program, chatsListUseCase) {
+	program.command("chats").description("List chats").option("--type <type>", "Filter by chat type: private, group, supergroup, channel").option("--limit <n>", "Number of chats to show", "50").option("--offset <n>", "Offset for pagination", "0").action(async (opts) => {
+		try {
+			if (opts.type && !VALID_TYPES.includes(opts.type)) {
+				console.error(chalk.red(`Invalid chat type. Use: ${VALID_TYPES.join(", ")}`));
+				process.exit(1);
+			}
+			const chats = await chatsListUseCase.execute({
+				alias: program.opts().account,
+				limit: parseInt(opts.limit, 10),
+				offset: parseInt(opts.offset, 10),
+				type: opts.type
+			});
+			const json = program.opts().json;
+			console.log(json ? formatChatsJson(chats) : formatChatsTable(chats));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error(chalk.red(message));
+			process.exit(message.includes("No default") || message.includes("expired") ? 2 : 1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/default.ts
+function registerDefaultCommand(program, setDefaultUseCase) {
+	program.command("default <alias>").description("Set the default account").action(async (alias) => {
+		try {
+			const account = await setDefaultUseCase.execute(alias);
+			const name = account.lastName ? `${account.firstName} ${account.lastName}` : account.firstName;
+			console.log(chalk.green(`Default account set to "${account.alias}" (${account.phone}, ${name})`));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			if (message.includes("already the default")) {
+				console.log(message);
+				process.exit(0);
+			}
+			console.error(chalk.red(message));
+			process.exit(message.includes("not found") ? 1 : 2);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/download.ts
+function registerDownloadCommand(program, downloadMediaUseCase) {
+	program.command("download <chat> <messageId>").description("Download media from a message").option("--out <dir>", "Output directory", ".").action(async (chat, messageId, opts) => {
+		try {
+			const json = program.opts().json;
+			let progressBar = null;
+			if (!json) progressBar = new SingleBar({ format: "{bar} {percentage}% | {value}/{total} bytes" }, Presets.shades_classic);
+			const result = await downloadMediaUseCase.execute({
+				alias: program.opts().account,
+				chat,
+				messageId: parseInt(messageId, 10),
+				outputDir: opts.out,
+				onProgress: json ? void 0 : (downloaded, total) => {
+					if (progressBar) {
+						if (total > 0 && !progressBar.isActive) progressBar.start(total, 0);
+						progressBar.update(downloaded);
+					}
+				}
+			});
+			progressBar?.stop();
+			if (json) console.log(JSON.stringify(result, null, 2));
+			else console.log(chalk.green(`\nSaved to ${result.path}`));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error(chalk.red(message));
+			process.exit(message.includes("No default") || message.includes("expired") ? 2 : 1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/logout.ts
+function registerLogoutCommand(program, logoutUseCase) {
+	program.command("logout [alias]").description("Log out from a Telegram account").action(async (alias) => {
+		try {
+			const { account, othersExist } = await logoutUseCase.execute(alias);
+			const name = account.lastName ? `${account.firstName} ${account.lastName}` : account.firstName;
+			console.log(chalk.green(`Logged out from "${account.alias}" (${account.phone}, ${name})`));
+			if (account.isDefault && othersExist) console.log(chalk.yellow(`No default account set. Use 'tg default <alias>' to set one.`));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error(chalk.red(message));
+			process.exit(message.includes("No accounts") ? 2 : 1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/formatters/message-formatter.ts
+function formatDate(date) {
+	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")} ${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}
+function formatMediaPlaceholder(media) {
+	switch (media.type) {
+		case "photo": return "[Photo]";
+		case "video": return media.fileName ? `[Video: ${media.fileName}${media.size ? `, ${formatSize(media.size)}` : ""}]` : "[Video]";
+		case "document": return media.fileName ? `[Document: ${media.fileName}${media.size ? `, ${formatSize(media.size)}` : ""}]` : "[Document]";
+		case "audio": return media.fileName ? `[Audio: ${media.fileName}]` : "[Audio]";
+		case "voice": return "[Voice]";
+		case "video_note": return "[Video message]";
+		case "sticker": return "[Sticker]";
+		case "animation": return "[GIF]";
+		default: return "[Media]";
+	}
+}
+function formatSize(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+function formatMessagesText(messages) {
+	if (messages.length === 0) return "";
+	return messages.map((msg) => {
+		const lines = [`${chalk.dim(`[${formatDate(msg.date)}]`)} ${chalk.cyan(`#${msg.id}`)} ${chalk.bold(msg.senderName)}:`];
+		if (msg.text) lines.push(`  ${msg.text}`);
+		if (msg.media) lines.push(`  ${chalk.italic(formatMediaPlaceholder(msg.media))}`);
+		if (!msg.text && !msg.media) lines.push(`  ${chalk.dim("[empty message]")}`);
+		return lines.join("\n");
+	}).join("\n\n");
+}
+function formatMessagesJson(messages) {
+	return JSON.stringify(messages, null, 2);
+}
+
+//#endregion
+//#region src/cli/commands/messages.ts
+function parseAfterDate(value) {
+	if (/^\d{1,2}:\d{2}$/.test(value)) {
+		const today = /* @__PURE__ */ new Date();
+		const [h, m] = value.split(":").map(Number);
+		today.setHours(h, m, 0, 0);
+		return today;
+	}
+	const parsed = new Date(value);
+	if (Number.isNaN(parsed.getTime())) throw new Error("Invalid date format. Use: YYYY-MM-DD, YYYY-MM-DDTHH:mm, or HH:mm");
+	return parsed;
+}
+function registerMessagesCommand(program, messagesListUseCase) {
+	program.command("messages <chat>").description("List messages from a chat").option("-n <count>", "Number of messages to load", "100").option("--all", "Load all messages", false).option("--topic <id>", "Load messages from a specific forum topic").option("--after <datetime>", "Show messages after given time (YYYY-MM-DD, YYYY-MM-DDTHH:mm, HH:mm)").action(async (chat, opts) => {
+		try {
+			const json = program.opts().json;
+			const after = opts.after ? parseAfterDate(opts.after) : void 0;
+			const messages = await messagesListUseCase.execute({
+				alias: program.opts().account,
+				chat,
+				limit: parseInt(opts.n, 10),
+				all: opts.all,
+				threadId: opts.topic ? parseInt(opts.topic, 10) : void 0,
+				after,
+				onProgress: json ? void 0 : (loaded) => {
+					process.stderr.write(`\rLoading messages... ${loaded} loaded`);
+				}
+			});
+			if (!json && (opts.all || after)) process.stderr.write(`\r${" ".repeat(50)}\r`);
+			console.log(json ? formatMessagesJson(messages) : formatMessagesText(messages));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error(chalk.red(message));
+			process.exit(message.includes("No default") || message.includes("expired") ? 2 : 1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/formatters/topic-formatter.ts
+function formatTopicsTable(topics) {
+	if (topics.length === 0) return chalk.yellow("No topics found. This chat may not be a forum.");
+	const table = new Table({
+		head: [
+			"#",
+			"Topic ID",
+			"Title",
+			"Unread",
+			"Status"
+		],
+		style: { head: ["cyan"] }
+	});
+	topics.forEach((topic, i) => {
+		const status = topic.isClosed ? chalk.dim("closed") : chalk.green("open");
+		const pin = topic.isPinned ? ` ${chalk.yellow("pinned")}` : "";
+		table.push([
+			i + 1,
+			topic.id,
+			topic.title,
+			topic.unreadCount > 0 ? chalk.bold(String(topic.unreadCount)) : "—",
+			status + pin
+		]);
+	});
+	return table.toString();
+}
+function formatTopicsJson(topics) {
+	return JSON.stringify(topics, null, 2);
+}
+
+//#endregion
+//#region src/cli/commands/topics.ts
+function registerTopicsCommand(program, topicsListUseCase) {
+	program.command("topics <chat>").description("List forum topics in a supergroup").option("--limit <n>", "Number of topics to show", "100").action(async (chat, opts) => {
+		try {
+			const topics = await topicsListUseCase.execute({
+				alias: program.opts().account,
+				chat,
+				limit: parseInt(opts.limit, 10)
+			});
+			const json = program.opts().json;
+			console.log(json ? formatTopicsJson(topics) : formatTopicsTable(topics));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error(chalk.red(message));
+			process.exit(message.includes("No default") ? 2 : 1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/app.ts
+function createApp(useCases) {
+	const program = new Command();
+	program.name("tg").description("CLI for Telegram via MTProto").version("0.1.0").option("--account <alias>", "Use a specific account instead of default").option("--json", "Output in JSON format");
+	registerAuthCommand(program, useCases.auth);
+	registerLogoutCommand(program, useCases.logout);
+	registerAccountsCommand(program, useCases.accountsList, useCases.accountsRename);
+	registerDefaultCommand(program, useCases.setDefault);
+	registerChatsCommand(program, useCases.chatsList);
+	registerMessagesCommand(program, useCases.messagesList);
+	registerDownloadCommand(program, useCases.downloadMedia);
+	registerTopicsCommand(program, useCases.topicsList);
+	return program;
+}
+
+//#endregion
+//#region src/infrastructure/keychain-credential-storage.ts
+const SERVICE = "tg-mtproto-cli";
+const KEY_API_CREDENTIALS = "api_credentials";
+const KEY_ACCOUNTS_INDEX = "accounts_index";
+const KEY_DEFAULT_ACCOUNT = "default_account";
+const accountKey = (alias) => `account.${alias}`;
+async function readJson(account) {
+	const raw = await getPassword(SERVICE, account);
+	if (!raw) return null;
+	return JSON.parse(raw);
+}
+async function writeJson(account, data) {
+	await setPassword(SERVICE, account, JSON.stringify(data));
+}
+var KeychainCredentialStorage = class {
+	async getAccounts() {
+		const aliases = await readJson(KEY_ACCOUNTS_INDEX);
+		if (!aliases || aliases.length === 0) return [];
+		const accounts = [];
+		for (const alias of aliases) {
+			const acc = await readJson(accountKey(alias));
+			if (acc) accounts.push(acc);
+		}
+		return accounts;
+	}
+	async getAccountByAlias(alias) {
+		return readJson(accountKey(alias));
+	}
+	async getDefaultAccount() {
+		const defaultAlias = await getPassword(SERVICE, KEY_DEFAULT_ACCOUNT);
+		if (!defaultAlias) return null;
+		const alias = JSON.parse(defaultAlias);
+		return this.getAccountByAlias(alias);
+	}
+	async saveAccount(account) {
+		await writeJson(accountKey(account.alias), account);
+		const aliases = await readJson(KEY_ACCOUNTS_INDEX) ?? [];
+		if (!aliases.includes(account.alias)) {
+			aliases.push(account.alias);
+			await writeJson(KEY_ACCOUNTS_INDEX, aliases);
+		}
+	}
+	async removeAccount(alias) {
+		await deletePassword(SERVICE, accountKey(alias));
+		await writeJson(KEY_ACCOUNTS_INDEX, (await readJson(KEY_ACCOUNTS_INDEX) ?? []).filter((a) => a !== alias));
+		const defaultAlias = await getPassword(SERVICE, KEY_DEFAULT_ACCOUNT);
+		if (defaultAlias && JSON.parse(defaultAlias) === alias) await deletePassword(SERVICE, KEY_DEFAULT_ACCOUNT);
+	}
+	async setDefault(alias) {
+		const accounts = await this.getAccounts();
+		for (const acc of accounts) {
+			const updated = {
+				...acc,
+				isDefault: acc.alias === alias
+			};
+			await writeJson(accountKey(acc.alias), updated);
+		}
+		await writeJson(KEY_DEFAULT_ACCOUNT, alias);
+	}
+	async isAliasAvailable(alias) {
+		return await readJson(accountKey(alias)) === null;
+	}
+	async renameAlias(oldAlias, newAlias) {
+		const account = await readJson(accountKey(oldAlias));
+		if (!account) throw new Error(`Account "${oldAlias}" not found`);
+		const updated = {
+			...account,
+			alias: newAlias
+		};
+		await writeJson(accountKey(newAlias), updated);
+		await deletePassword(SERVICE, accountKey(oldAlias));
+		const aliases = await readJson(KEY_ACCOUNTS_INDEX) ?? [];
+		const idx = aliases.indexOf(oldAlias);
+		if (idx !== -1) aliases[idx] = newAlias;
+		await writeJson(KEY_ACCOUNTS_INDEX, aliases);
+		const defaultAlias = await getPassword(SERVICE, KEY_DEFAULT_ACCOUNT);
+		if (defaultAlias && JSON.parse(defaultAlias) === oldAlias) await writeJson(KEY_DEFAULT_ACCOUNT, newAlias);
+	}
+	async getApiCredentials() {
+		return readJson(KEY_API_CREDENTIALS);
+	}
+	async saveApiCredentials(apiId, apiHash) {
+		await writeJson(KEY_API_CREDENTIALS, {
+			apiId,
+			apiHash
+		});
+	}
+};
+
+//#endregion
+//#region src/infrastructure/sqlite-session-storage.ts
+var SqliteSessionStorage = class {
+	sessionsDir;
+	constructor() {
+		this.sessionsDir = join(homedir(), ".tg-mtproto-cli", "sessions");
+		mkdirSync(this.sessionsDir, { recursive: true });
+	}
+	getSessionPath(phone) {
+		return join(this.sessionsDir, `${phone}.session`);
+	}
+	sessionExists(phone) {
+		return existsSync(this.getSessionPath(phone));
+	}
+	async removeSession(phone) {
+		const path = this.getSessionPath(phone);
+		if (existsSync(path)) unlinkSync(path);
+	}
+};
+
+//#endregion
+//#region src/infrastructure/mtcute-telegram-gateway.ts
+function mapMediaTypeFromMtcute(media) {
+	switch (media.type) {
+		case "photo": return "photo";
+		case "video": return "video";
+		case "document": return "document";
+		case "audio": return "audio";
+		case "voice": return "voice";
+		case "sticker": return "sticker";
+		default: return null;
+	}
+}
+function mapMedia(raw) {
+	if (!raw) return null;
+	const mediaType = mapMediaTypeFromMtcute(raw);
+	if (!mediaType) return null;
+	let fileName = null;
+	let mimeType = null;
+	let size = null;
+	if ("fileName" in raw && typeof raw.fileName === "string") fileName = raw.fileName;
+	if ("mimeType" in raw && typeof raw.mimeType === "string") mimeType = raw.mimeType;
+	if ("fileSize" in raw && typeof raw.fileSize === "number") size = raw.fileSize;
+	if (!mimeType) mimeType = {
+		photo: "image/jpeg",
+		sticker: "image/webp",
+		voice: "audio/ogg"
+	}[mediaType] ?? null;
+	return {
+		type: mediaType,
+		fileName,
+		mimeType,
+		size
+	};
+}
+const MIME_EXT = {
+	"image/jpeg": ".jpg",
+	"image/png": ".png",
+	"image/webp": ".webp",
+	"image/gif": ".gif",
+	"video/mp4": ".mp4",
+	"video/quicktime": ".mov",
+	"audio/mpeg": ".mp3",
+	"audio/ogg": ".ogg",
+	"application/pdf": ".pdf"
+};
+function extFromMime(mime) {
+	if (!mime) return "";
+	return MIME_EXT[mime] ?? "";
+}
+function parseChatId(chatId) {
+	if (typeof chatId === "number") return chatId;
+	const num = Number(chatId);
+	return Number.isFinite(num) ? num : chatId;
+}
+function mapPeerChatType(peer) {
+	switch (peer.type) {
+		case "user":
+		case "bot": return "private";
+		case "group": return "group";
+		case "supergroup": return "supergroup";
+		case "channel": return "channel";
+		default: return "private";
+	}
+}
+var MtcuteTelegramGateway = class {
+	client;
+	constructor(params) {
+		this.client = new TelegramClient({
+			apiId: params.apiId,
+			apiHash: params.apiHash,
+			storage: params.sessionPath
+		});
+	}
+	async connect() {
+		await this.client.connect();
+	}
+	async disconnect() {
+		await this.client.destroy();
+	}
+	async auth(params) {
+		const user = await this.client.start({
+			phone: params.phone,
+			password: params.password,
+			qrCodeHandler: (url) => {
+				console.log(encodeQR(url, "ascii"));
+			}
+		});
+		return {
+			id: user.id,
+			phone: user.phoneNumber ?? "",
+			firstName: user.firstName ?? "",
+			lastName: user.lastName ?? null,
+			username: user.username ?? null,
+			alias: "",
+			isDefault: false
+		};
+	}
+	async logout() {
+		await this.client.logOut();
+	}
+	async getChats(params) {
+		const chats = [];
+		let count = 0;
+		for await (const dialog of this.client.iterDialogs({ limit: params.limit + params.offset })) {
+			if (count < params.offset) {
+				count++;
+				continue;
+			}
+			const peer = dialog.peer;
+			const chatType = mapPeerChatType(peer);
+			if (params.type && chatType !== params.type) continue;
+			const lastMsg = dialog.lastMessage;
+			let lastMessageText = null;
+			if (lastMsg) {
+				const text = lastMsg.text;
+				if (text) lastMessageText = text.length > 100 ? `${text.slice(0, 100)}...` : text;
+				else if (lastMsg.media) lastMessageText = `[${lastMsg.media.type}]`;
+			}
+			chats.push({
+				id: peer.id,
+				type: chatType,
+				title: peer.displayName,
+				username: "username" in peer ? peer.username ?? null : null,
+				unreadCount: dialog.unreadCount,
+				lastMessage: lastMessageText,
+				lastActivity: lastMsg?.date ?? /* @__PURE__ */ new Date()
+			});
+			if (chats.length >= params.limit) break;
+		}
+		return chats;
+	}
+	async getMessages(params) {
+		const resolvedChatId = parseChatId(params.chatId);
+		const scanLimit = params.after ? Infinity : params.all ? Infinity : params.limit;
+		let messages;
+		if (params.threadId) messages = await this.getMessagesByThread(resolvedChatId, params.threadId, scanLimit, params.after, params.onProgress);
+		else messages = await this.getMessagesByHistory(resolvedChatId, scanLimit, params.after, params.onProgress);
+		if (!params.all && params.limit < messages.length) return messages.slice(-params.limit);
+		return messages;
+	}
+	async getMessagesByHistory(chatId, limit, after, onProgress) {
+		if (after) return this.getHistoryForward(chatId, after, onProgress);
+		return this.getHistoryBackward(chatId, limit, onProgress);
+	}
+	async getHistoryForward(chatId, after, onProgress) {
+		const messages = [];
+		let offset = {
+			id: 0,
+			date: Math.floor(after.getTime() / 1e3)
+		};
+		let loaded = 0;
+		while (true) {
+			const batch = await this.client.getHistory(chatId, {
+				limit: 100,
+				offset,
+				reverse: true
+			});
+			if (batch.length === 0) break;
+			for (const msg of batch) messages.push({
+				id: msg.id,
+				chatId: msg.chat.id,
+				senderName: msg.sender.displayName,
+				text: msg.text || null,
+				date: msg.date,
+				media: mapMedia(msg.media),
+				replyToId: msg.replyToMessage?.id ?? null,
+				isOutgoing: msg.isOutgoing
+			});
+			loaded += batch.length;
+			onProgress?.(loaded);
+			const lastMsg = batch[batch.length - 1];
+			offset = {
+				id: lastMsg.id,
+				date: Math.floor(lastMsg.date.getTime() / 1e3)
+			};
+			if (batch.length < 100) break;
+		}
+		return messages;
+	}
+	async getHistoryBackward(chatId, limit, onProgress) {
+		const messages = [];
+		let offset;
+		let loaded = 0;
+		while (loaded < limit) {
+			const batchSize = Math.min(limit === Infinity ? 100 : limit - loaded, 100);
+			const batch = await this.client.getHistory(chatId, {
+				limit: batchSize,
+				offset
+			});
+			if (batch.length === 0) break;
+			for (const msg of batch) messages.push({
+				id: msg.id,
+				chatId: msg.chat.id,
+				senderName: msg.sender.displayName,
+				text: msg.text || null,
+				date: msg.date,
+				media: mapMedia(msg.media),
+				replyToId: msg.replyToMessage?.id ?? null,
+				isOutgoing: msg.isOutgoing
+			});
+			loaded += batch.length;
+			onProgress?.(loaded);
+			const lastMsg = batch[batch.length - 1];
+			if (lastMsg) offset = {
+				id: lastMsg.id,
+				date: Math.floor(lastMsg.date.getTime() / 1e3)
+			};
+			if (batch.length < batchSize) break;
+		}
+		messages.reverse();
+		return messages;
+	}
+	async getMessagesByThread(chatId, threadId, limit, after, onProgress) {
+		const messages = [];
+		let searchOffset = 0;
+		let loaded = 0;
+		let hitDateBoundary = false;
+		while (loaded < limit && !hitDateBoundary) {
+			const batchSize = Math.min(limit === Infinity ? 100 : limit - loaded, 100);
+			const batch = await this.client.searchMessages({
+				chatId,
+				threadId,
+				limit: batchSize,
+				offset: searchOffset
+			});
+			if (batch.length === 0) break;
+			for (const msg of batch) {
+				if (after && msg.date < after) {
+					hitDateBoundary = true;
+					break;
+				}
+				messages.push({
+					id: msg.id,
+					chatId: msg.chat.id,
+					senderName: msg.sender.displayName,
+					text: msg.text || null,
+					date: msg.date,
+					media: mapMedia(msg.media),
+					replyToId: msg.replyToMessage?.id ?? null,
+					isOutgoing: msg.isOutgoing
+				});
+			}
+			loaded += batch.length;
+			onProgress?.(loaded);
+			searchOffset = batch[batch.length - 1].id;
+			if (batch.length < batchSize) break;
+		}
+		messages.reverse();
+		return messages;
+	}
+	async downloadMedia(params) {
+		const [msg] = await this.client.getMessages(parseChatId(params.chatId), params.messageId);
+		if (!msg) throw new Error(`Message #${params.messageId} not found`);
+		if (!msg.media) throw new Error(`Message #${params.messageId} has no media attachment`);
+		const media = mapMedia(msg.media);
+		const fileName = media?.fileName ?? `${media?.type ?? "file"}_${params.messageId}${extFromMime(media?.mimeType)}`;
+		const fullPath = params.outputPath.endsWith("/") ? `${params.outputPath}${fileName}` : `${params.outputPath}/${fileName}`;
+		let totalSize = media?.size ?? 0;
+		let downloaded = 0;
+		const downloadable = msg.media;
+		await this.client.downloadToFile(fullPath, downloadable, { progressCallback: (current, total) => {
+			downloaded = Number(current);
+			totalSize = Number(total);
+			params.onProgress?.(downloaded, totalSize);
+		} });
+		return {
+			path: fullPath,
+			fileName,
+			size: totalSize,
+			mimeType: media?.mimeType ?? "application/octet-stream"
+		};
+	}
+	async getTopics(params) {
+		const resolvedChatId = parseChatId(params.chatId);
+		const topics = [];
+		for await (const topic of this.client.iterForumTopics(resolvedChatId, { limit: params.limit })) {
+			topics.push({
+				id: topic.id,
+				title: topic.title,
+				unreadCount: topic.unreadCount,
+				isClosed: topic.isClosed,
+				isPinned: topic.isPinned
+			});
+			if (topics.length >= params.limit) break;
+		}
+		return topics;
+	}
+	async resolveChat(identifier) {
+		const peer = await this.client.resolvePeer(parseChatId(identifier));
+		let type = "private";
+		let id = 0;
+		switch (peer._) {
+			case "inputPeerUser":
+				type = "private";
+				id = Number(peer.userId);
+				break;
+			case "inputPeerChat":
+				type = "group";
+				id = Number(peer.chatId);
+				break;
+			case "inputPeerChannel":
+				type = "supergroup";
+				id = Number(peer.channelId);
+				break;
+		}
+		return {
+			id,
+			type
+		};
+	}
+};
+
+//#endregion
+//#region src/infrastructure/telegram-gateway-factory.ts
+const createTelegramGateway = (params) => {
+	return new MtcuteTelegramGateway(params);
+};
+
+//#endregion
+//#region src/use-cases/accounts-list.ts
+var AccountsListUseCase = class {
+	constructor(credentialStorage) {
+		this.credentialStorage = credentialStorage;
+	}
+	async execute() {
+		return this.credentialStorage.getAccounts();
+	}
+};
+
+//#endregion
+//#region src/use-cases/accounts-rename.ts
+const ALIAS_REGEX = /^[a-zA-Z0-9_-]+$/;
+var AccountsRenameUseCase = class {
+	constructor(credentialStorage) {
+		this.credentialStorage = credentialStorage;
+	}
+	async execute(oldAlias, newAlias) {
+		if (oldAlias === newAlias) throw new Error(`Alias is already "${oldAlias}"`);
+		if (!ALIAS_REGEX.test(newAlias)) throw new Error("Invalid alias format. Use: letters, digits, hyphens, underscores");
+		if (!await this.credentialStorage.getAccountByAlias(oldAlias)) throw new Error(`Account "${oldAlias}" not found`);
+		if (!await this.credentialStorage.isAliasAvailable(newAlias)) throw new Error(`Alias "${newAlias}" is already taken`);
+		await this.credentialStorage.renameAlias(oldAlias, newAlias);
+	}
+};
+
+//#endregion
+//#region src/use-cases/auth.ts
+var AuthUseCase = class {
+	constructor(credentialStorage, sessionStorage, createGateway) {
+		this.credentialStorage = credentialStorage;
+		this.sessionStorage = sessionStorage;
+		this.createGateway = createGateway;
+	}
+	async execute(callbacks) {
+		let apiCreds = await this.credentialStorage.getApiCredentials();
+		if (!apiCreds) {
+			const apiId = await callbacks.promptApiId();
+			const apiHash = await callbacks.promptApiHash();
+			await this.credentialStorage.saveApiCredentials(apiId, apiHash);
+			apiCreds = {
+				apiId,
+				apiHash
+			};
+		}
+		const phone = (await callbacks.promptPhone()).replace(/[\s()-]/g, "");
+		const accounts = await this.credentialStorage.getAccounts();
+		const normalizedDigits = phone.replace(/\D/g, "");
+		const existing = accounts.find((a) => a.phone.replace(/\D/g, "") === normalizedDigits);
+		if (existing) {
+			if (!await callbacks.onAlreadyLoggedIn(existing)) throw new Error("Authentication cancelled");
+			await this.sessionStorage.removeSession(existing.phone);
+			await this.credentialStorage.removeAccount(existing.alias);
+		}
+		const sessionPath = this.sessionStorage.getSessionPath(phone);
+		const gateway = this.createGateway({
+			apiId: apiCreds.apiId,
+			apiHash: apiCreds.apiHash,
+			sessionPath
+		});
+		try {
+			await gateway.connect();
+			const rawAccount = await gateway.auth({
+				phone: async () => phone,
+				code: callbacks.promptCode,
+				password: callbacks.promptPassword
+			});
+			const defaultAlias = rawAccount.username ?? phone;
+			let alias = await callbacks.promptAlias(defaultAlias);
+			if (!alias) alias = defaultAlias;
+			while (!await this.credentialStorage.isAliasAvailable(alias)) {
+				callbacks.onAliasTaken(alias);
+				alias = await callbacks.promptAlias(defaultAlias);
+				if (!alias) alias = defaultAlias;
+			}
+			const isFirst = accounts.length === 0 || existing && accounts.length === 1;
+			const account = {
+				...rawAccount,
+				phone,
+				alias,
+				isDefault: !!isFirst
+			};
+			await this.credentialStorage.saveAccount(account);
+			if (isFirst) await this.credentialStorage.setDefault(alias);
+			return account;
+		} finally {
+			await gateway.disconnect();
+		}
+	}
+};
+
+//#endregion
+//#region src/use-cases/chats-list.ts
+var ChatsListUseCase = class {
+	constructor(credentialStorage, sessionStorage, createGateway) {
+		this.credentialStorage = credentialStorage;
+		this.sessionStorage = sessionStorage;
+		this.createGateway = createGateway;
+	}
+	async execute(params) {
+		const account = params.alias ? await this.credentialStorage.getAccountByAlias(params.alias) : await this.credentialStorage.getDefaultAccount();
+		if (!account) throw new Error("No default account. Use 'tg default <alias>' or --account flag.");
+		const apiCreds = await this.credentialStorage.getApiCredentials();
+		if (!apiCreds) throw new Error("No API credentials. Run 'tg auth' first.");
+		const sessionPath = this.sessionStorage.getSessionPath(account.phone);
+		const gateway = this.createGateway({
+			apiId: apiCreds.apiId,
+			apiHash: apiCreds.apiHash,
+			sessionPath
+		});
+		try {
+			await gateway.connect();
+			return await gateway.getChats({
+				limit: params.limit,
+				offset: params.offset,
+				type: params.type
+			});
+		} finally {
+			await gateway.disconnect();
+		}
+	}
+};
+
+//#endregion
+//#region src/use-cases/download-media.ts
+var DownloadMediaUseCase = class {
+	constructor(credentialStorage, sessionStorage, createGateway) {
+		this.credentialStorage = credentialStorage;
+		this.sessionStorage = sessionStorage;
+		this.createGateway = createGateway;
+	}
+	async execute(params) {
+		const account = params.alias ? await this.credentialStorage.getAccountByAlias(params.alias) : await this.credentialStorage.getDefaultAccount();
+		if (!account) throw new Error("No default account. Use 'tg default <alias>' or --account flag.");
+		const apiCreds = await this.credentialStorage.getApiCredentials();
+		if (!apiCreds) throw new Error("No API credentials. Run 'tg auth' first.");
+		const sessionPath = this.sessionStorage.getSessionPath(account.phone);
+		const gateway = this.createGateway({
+			apiId: apiCreds.apiId,
+			apiHash: apiCreds.apiHash,
+			sessionPath
+		});
+		try {
+			await gateway.connect();
+			return await gateway.downloadMedia({
+				chatId: params.chat,
+				messageId: params.messageId,
+				outputPath: params.outputDir,
+				onProgress: params.onProgress
+			});
+		} finally {
+			await gateway.disconnect();
+		}
+	}
+};
+
+//#endregion
+//#region src/use-cases/logout.ts
+var LogoutUseCase = class {
+	constructor(credentialStorage, sessionStorage, createGateway) {
+		this.credentialStorage = credentialStorage;
+		this.sessionStorage = sessionStorage;
+		this.createGateway = createGateway;
+	}
+	async execute(alias) {
+		let account;
+		if (alias) {
+			account = await this.credentialStorage.getAccountByAlias(alias);
+			if (!account) throw new Error(`Account "${alias}" not found`);
+		} else {
+			account = await this.credentialStorage.getDefaultAccount();
+			if (!account) {
+				if ((await this.credentialStorage.getAccounts()).length === 0) throw new Error("No accounts found. Use 'tg auth' to log in.");
+				throw new Error("No default account set. Specify an alias or use 'tg default <alias>'.");
+			}
+		}
+		const apiCreds = await this.credentialStorage.getApiCredentials();
+		if (apiCreds) {
+			const sessionPath = this.sessionStorage.getSessionPath(account.phone);
+			const gateway = this.createGateway({
+				apiId: apiCreds.apiId,
+				apiHash: apiCreds.apiHash,
+				sessionPath
+			});
+			try {
+				await gateway.connect();
+				await gateway.logout();
+			} catch {} finally {
+				await gateway.disconnect();
+			}
+		}
+		await this.sessionStorage.removeSession(account.phone);
+		await this.credentialStorage.removeAccount(account.alias);
+		const remaining = await this.credentialStorage.getAccounts();
+		return {
+			account,
+			othersExist: remaining.length > 0
+		};
+	}
+};
+
+//#endregion
+//#region src/use-cases/messages-list.ts
+var MessagesListUseCase = class {
+	constructor(credentialStorage, sessionStorage, createGateway) {
+		this.credentialStorage = credentialStorage;
+		this.sessionStorage = sessionStorage;
+		this.createGateway = createGateway;
+	}
+	async execute(params) {
+		const account = params.alias ? await this.credentialStorage.getAccountByAlias(params.alias) : await this.credentialStorage.getDefaultAccount();
+		if (!account) throw new Error("No default account. Use 'tg default <alias>' or --account flag.");
+		const apiCreds = await this.credentialStorage.getApiCredentials();
+		if (!apiCreds) throw new Error("No API credentials. Run 'tg auth' first.");
+		const sessionPath = this.sessionStorage.getSessionPath(account.phone);
+		const gateway = this.createGateway({
+			apiId: apiCreds.apiId,
+			apiHash: apiCreds.apiHash,
+			sessionPath
+		});
+		try {
+			await gateway.connect();
+			return await gateway.getMessages({
+				chatId: params.chat,
+				limit: params.limit,
+				all: params.all,
+				threadId: params.threadId,
+				after: params.after,
+				onProgress: params.onProgress
+			});
+		} finally {
+			await gateway.disconnect();
+		}
+	}
+};
+
+//#endregion
+//#region src/use-cases/set-default-account.ts
+var SetDefaultAccountUseCase = class {
+	constructor(credentialStorage) {
+		this.credentialStorage = credentialStorage;
+	}
+	async execute(alias) {
+		const account = await this.credentialStorage.getAccountByAlias(alias);
+		if (!account) throw new Error(`Account "${alias}" not found`);
+		if (account.isDefault) throw new Error(`Account "${alias}" is already the default`);
+		await this.credentialStorage.setDefault(alias);
+		return {
+			...account,
+			isDefault: true
+		};
+	}
+};
+
+//#endregion
+//#region src/use-cases/topics-list.ts
+var TopicsListUseCase = class {
+	constructor(credentialStorage, sessionStorage, createGateway) {
+		this.credentialStorage = credentialStorage;
+		this.sessionStorage = sessionStorage;
+		this.createGateway = createGateway;
+	}
+	async execute(params) {
+		const account = params.alias ? await this.credentialStorage.getAccountByAlias(params.alias) : await this.credentialStorage.getDefaultAccount();
+		if (!account) throw new Error("No default account. Use 'tg default <alias>' or --account flag.");
+		const apiCreds = await this.credentialStorage.getApiCredentials();
+		if (!apiCreds) throw new Error("No API credentials. Run 'tg auth' first.");
+		const sessionPath = this.sessionStorage.getSessionPath(account.phone);
+		const gateway = this.createGateway({
+			apiId: apiCreds.apiId,
+			apiHash: apiCreds.apiHash,
+			sessionPath
+		});
+		try {
+			await gateway.connect();
+			return await gateway.getTopics({
+				chatId: params.chat,
+				limit: params.limit
+			});
+		} finally {
+			await gateway.disconnect();
+		}
+	}
+};
+
+//#endregion
+//#region src/main.ts
+const credentialStorage = new KeychainCredentialStorage();
+const sessionStorage = new SqliteSessionStorage();
+createApp({
+	auth: new AuthUseCase(credentialStorage, sessionStorage, createTelegramGateway),
+	logout: new LogoutUseCase(credentialStorage, sessionStorage, createTelegramGateway),
+	accountsList: new AccountsListUseCase(credentialStorage),
+	accountsRename: new AccountsRenameUseCase(credentialStorage),
+	setDefault: new SetDefaultAccountUseCase(credentialStorage),
+	chatsList: new ChatsListUseCase(credentialStorage, sessionStorage, createTelegramGateway),
+	messagesList: new MessagesListUseCase(credentialStorage, sessionStorage, createTelegramGateway),
+	downloadMedia: new DownloadMediaUseCase(credentialStorage, sessionStorage, createTelegramGateway),
+	topicsList: new TopicsListUseCase(credentialStorage, sessionStorage, createTelegramGateway)
+}).parseAsync(process.argv);
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "tg-mtproto-cli",
+  "version": "0.1.0",
+  "description": "CLI for Telegram via MTProto — chats, messages, media download, multi-account",
+  "type": "module",
+  "bin": {
+    "tg": "./dist/main.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "start": "node dist/main.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src",
+    "lint:fix": "biome check --write src",
+    "format": "biome format --write src",
+    "prepublishOnly": "npm run lint && npm run build"
+  },
+  "keywords": [
+    "telegram",
+    "mtproto",
+    "cli",
+    "tg",
+    "mtcute",
+    "chat",
+    "messages",
+    "telegram-client"
+  ],
+  "author": "cyberash",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyberash-dev/tg-mtproto-cli.git"
+  },
+  "homepage": "https://github.com/cyberash-dev/tg-mtproto-cli#readme",
+  "bugs": {
+    "url": "https://github.com/cyberash-dev/tg-mtproto-cli/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@mtcute/node": "0.28.1",
+    "chalk": "5.6.2",
+    "cli-progress": "3.12.0",
+    "cli-table3": "0.6.5",
+    "commander": "14.0.3",
+    "cross-keychain": "1.1.0",
+    "qr": "0.5.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.4",
+    "@types/cli-progress": "3.11.6",
+    "@types/node": "25.3.0",
+    "tsdown": "0.20.3",
+    "typescript": "5.9.3"
+  }
+}