@will-17173/telegram-cli 0.3.0 → 0.4.0

package/README.md

@@ -4,22 +4,21 @@
 
 A TypeScript command-line client for syncing Telegram chats, listening to live messages, searching locally stored messages, and inspecting groups from the terminal.
 
-## Features
-
-- Sign in to Telegram and inspect the current account or available chats.
-- Manage multiple Telegram accounts with isolated sessions, message databases, and interactive account switching.
-- Fetch chat history into a local SQLite database for fast, offline search.
-- Sync one chat incrementally or sync many chats with a single command.
-- Listen for new messages in real time, with optional attachment summaries.
-- Download attachments from channels that restrict content saving.
-- Search, filter, summarize, and export locally stored messages, with reply context and media-group summaries in recent results.
+## What you can do
+
+- Manage multiple Telegram accounts with isolated sessions and message databases.
+- Inspect unread chats and read or search messages without storing them locally.
+- Sync chat history to SQLite for offline search, filtering, analysis, and export.
+- Archive selected chats as incremental Markdown files, with optional attachment downloads.
+- Listen for new messages and download incoming attachments.
 - Send, edit, and delete messages from the command line.
-- Inspect and manage groups, members, administrators, invites, forum topics, and messages.
-- Use human-readable output or structured JSON/YAML where supported.
+- Inspect contacts, notification settings, chat folders, groups, members, administrators, invites, and forum topics.
+- Disable remote Telegram mutations while keeping read-only and local commands available.
+- Use human-readable, JSON, YAML, or Markdown output in scripts and agent workflows.
 
 ## Built for AI agents
 
-Telegram CLI gives AI agents a command-based interface to Telegram and locally synced messages. After a human authenticates an account with `tg account add`, an agent can run online and local commands without browser automation.
+Telegram CLI gives AI agents a command-based interface to Telegram and locally synced messages. After you authenticate an account with `tg account add`, an agent can run online and local commands without browser automation.
 
 The CLI supports agent workflows through these interfaces:
 
@@ -49,15 +48,79 @@ Add `--global` to make the skill available across projects instead of installing
 
 Telegram CLI requires Node.js 22 or later.
 
-After the package is published to npm, install it globally with:
+Install the package globally from npm:
 
 ```sh
 npm install -g @will-17173/telegram-cli
 ```
 
+## Quick start
+
+Authenticate an account, check its status, and list its chats:
+
+```sh
+tg account add
+tg status
+tg chats
+tg chats --group
+tg chats --channel
+tg chats --user
+```
+
+Choose a chat name, username, or ID from `tg chats`, then sync and search its messages:
+
+```sh
+tg sync <chat>
+tg search "keyword" --chat <chat>
+```
+
+You can also sync multiple chats, listen for incoming messages, or send a message:
+
+```sh
+tg sync-all --max-chats 20 --delay 1
+tg listen <chat-or-id> --auto-download
+tg send <chat> "Hello from tg"
+```
+
+## Read and manage Telegram online
+
+`history`, `sync`, and `sync-all` fetch Telegram messages and store them in the local SQLite database. `read`, `search-online`, and `inbox` query Telegram directly without storing their results. `inbox` lists chats with unread messages without marking them as read.
+
+```sh
+tg inbox --markdown
+tg read @team --since 7d --until 2d
+tg search-online release --chat @team --json
+```
+
+Time bounds accept relative durations ending in `s`, `m`, `h`, `d`, or `w`. For example, `7d` means seven days before the command starts. Absolute bounds use ISO 8601 timestamps with a time zone, such as `2026-07-13T00:00:00Z`. The `--since` value must be earlier than `--until`.
+
+You can also inspect contacts, notification settings, folders, and group dialogs without changing remote state:
+
+```sh
+tg contact list
+tg contact info +8613800000000
+tg notification info @team
+tg folder list
+tg folder info 2
+tg group list --admin
+```
+
+The following commands modify Telegram remotely:
+
+```sh
+tg notification mute @team 8h
+tg notification unmute @team
+tg folder chat add Work @team
+tg folder chat remove Work @team
+```
+
+Use `tg config write-access off` to block these mutations. Restore them with `tg config write-access on`.
+
+Folder commands accept either a title or numeric folder ID. Folder titles are not necessarily unique. Run `tg folder list` first, then use the returned ID with `tg folder info`, `tg folder chat add`, or `tg folder chat remove`.
+
 ## Configuration
 
-Configuring personal Telegram API credentials is optional. To use your own, create them at [my.telegram.org](https://my.telegram.org), then save them with:
+Personal Telegram application programming interface (API) credentials are optional. To use your own, create them at [my.telegram.org](https://my.telegram.org), then save them with:
 
 ```sh
 tg config set --api-id <id> --api-hash <hash>
@@ -85,9 +148,7 @@ For a one-command override, set `TG_PROXY` in the command environment:
 TG_PROXY=http://127.0.0.1:8080 tg status
 ```
 
-Supported proxy forms are `socks4://`, `socks5://`, `http://`, and `https://` proxy URLs, plus MTProxy links in the forms `tg://proxy?...` and `https://t.me/proxy?...`. A non-empty `TG_PROXY` value, after trimming surrounding whitespace, overrides the persisted proxy. If `TG_PROXY` is empty or unset, the CLI falls back to the stored proxy; if neither is configured, it connects directly.
-
-The selected proxy applies to account login and every Telegram-backed command, not only the command used in the example. Proxy URLs can contain usernames and passwords or MTProxy secrets, so treat them as sensitive. CLI output does not print the configured proxy URL. A credential-bearing proxy URL entered literally on a command line may remain in shell history or be visible through process inspection. Provide `TG_PROXY` through an appropriately protected environment or secret-loading mechanism, or otherwise avoid placing literal secrets in shared shell histories and scripts.
+Telegram CLI supports SOCKS4, SOCKS5, HTTP, HTTPS, and MTProxy. The proxy applies to account login and every Telegram-backed command. Treat proxy URLs that contain credentials as sensitive.
 
 To inspect the effective configuration in human-readable, JSON, or YAML format, run:
 
@@ -98,9 +159,9 @@ tg config list --yaml
 tg config list --show-secrets
 ```
 
-This reports the effective configuration rather than the raw contents of `config.json`. API credentials are resolved from environment variables first, then stored configuration, then the built-in default. The proxy is resolved independently from `TG_PROXY` first, then stored configuration, then remains absent when neither is configured.
+This reports the effective configuration rather than the raw contents of `config.json`. The API hash is masked by default; `--show-secrets` reveals only the full API hash.
 
-The output reports exactly five fields: the effective API ID, API hash, credential source, proxy URL, and proxy source. The API hash is masked by default; use `--show-secrets` to display it in full. The proxy URL is always printed in full and may contain credentials or an MTProxy secret, so avoid writing `config list` output to logs or sharing it. `tg config list` does not create a Telegram client or make a network connection.
+Safe proxy endpoint details remain visible, but proxy usernames, passwords, and credential query parameters are always masked, even with `--show-secrets`.
 
 Run `tg account add` to authenticate and create a local session. Other commands never start the interactive login flow.
 
@@ -110,37 +171,6 @@ You can override the root directory for configuration, account sessions, and mes
 export DATA_DIR=/path/to/tg-cli-data
 ```
 
-## Quick start
-
-```sh
-# Add and authenticate the first account
-tg account add
-
-# Check authentication status
-tg status
-
-# List chats, then use a chat name, username, or ID where `<chat>` appears
-tg chats
-
-# Save a chat's history locally
-tg sync <chat>
-
-# Search the locally synced messages
-tg search "keyword" --chat <chat>
-
-# Sync across all chats
-tg sync-all --max-chats 20 --delay 1
-
-# Listen for new messages and automatically download incoming attachments
-tg listen <chat-or-id> --auto-download
-
-# Use plain output, download attachments, and hide their message summaries
-tg listen <chat-or-id> --no-interactive --auto-download --no-media
-
-# Send a message
-tg send <chat> "Hello from tg"
-```
-
 ## Send messages and attachments
 
 `send` requires `<chat>`. Send text, one or more files, or files with a caption:
@@ -160,6 +190,33 @@ tg send <chat> "Group caption" --file ./photo.jpg --file ./clip.mp4
 
 Telegram determines which file combinations and group sizes it accepts. If Telegram rejects the requested combination or limit, the command returns an error and does not silently split the files into separate messages or groups.
 
+## Archive chats as Markdown
+
+`archive` requires an explicit scope. Pass one or more chat IDs or usernames, or use `--all`, but don't combine them.
+
+The command uses the current account unless you pass `--account <name>`. It writes to that account's `archive` directory by default. Use `--output <path>` to select another directory.
+
+```sh
+# Initial archive with attachments: the preceding seven days
+tg archive @team --download-media
+
+# Custom range (relative durations or ISO timestamps with zones)
+tg archive @team --since 30d --until 2026-07-13T00:00:00Z
+
+# Full available history for every chat, including attachments
+tg archive --all --full --download-media
+```
+
+The first run archives the preceding seven days. Use `--since` and `--until` to select another range. Use `--full` to remove the lower bound; you can't combine it with `--since`.
+
+Later runs append new messages to the existing archive. Use `--rebuild` to replace each selected Markdown file. Without a new range, rebuilding reuses the archive's initial range.
+
+Use `--download-media` to store attachments in the archive's `media/` directory. Incremental runs retry referenced media that is still missing.
+
+Chat or attachment failures produce `archive_partial_failure`, preserve successful chat results, and exit with status 1. Use `--json` or `--yaml` in automation and inspect `completed`, `failed`, and `warnings`.
+
+Large history and media requests can trigger Telegram flood waits or other rate limits. Media downloads can fail independently. Successfully archived messages remain on disk, and warnings identify failed attachments.
+
 ## Multiple accounts
 
 Each Telegram account has its own persisted authentication session and local message database. Add and authenticate an account interactively with:
@@ -187,6 +244,15 @@ tg account switch <name>
 tg account remove <name> --force
 ```
 
+Log out explicitly to end the remote session without deleting the account, its settings, or locally stored messages. The `--yes` option confirms logout without a prompt.
+
+Logging in again requires an interactive terminal (TTY) and creates or replaces the local Telegram session. Scripts and non-interactive agents receive an `interaction_required` error.
+
+```sh
+tg account logout work --yes
+tg account login work
+```
+
 In an interactive terminal, `tg account switch` lists registered accounts, marks the current one, and accepts its number. Pass `<name>` when scripting or using `--json`, `--yaml`, or non-interactive input.
 
 Commands use the current account by default. Commands that support `--account` can target another registered account for one invocation without changing the current account:
@@ -203,7 +269,7 @@ Telegram API credentials apply to every registered account. You don't need to co
 
 ## Group management
 
-The `group` command keeps read-only inspection alongside management families for members, administrators, chat settings, invite links, forum topics, and messages. Use family help to see the current actions:
+The `group` command supports read-only inspection and management of members, administrators, chat settings, invite links, forum topics, and messages. Use each command group's help to see its actions:
 
 ```sh
 # Group details
@@ -220,19 +286,29 @@ tg group audit <chat> --query invite --user <user> --type member_invited --type
 
 # Management examples (the chat argument comes before action arguments)
 tg group member ban @team @alice --yes
+tg group admin transfer-owner @team @newowner --yes
 tg group chat slowmode @team 30s
 tg group topic --help
 ```
 
+After confirmation, ownership transfer securely prompts for the Telegram two-factor authentication (2FA) password. The password is never a CLI argument, stdin input, or environment automation source. The secure prompt accepts it only from an interactive terminal, not piped input. Don't automate this prompt.
+
 `group members` accepts exactly these seven `--type` filters: `recent`, `all`, `admins`, `banned`, `restricted`, `bots`, and `contacts`. It defaults to `recent` and 100 results; `--limit` accepts 1 through 200. Telegram can return fewer members than its reported total, so a page is not guaranteed to enumerate the whole group.
 
-`group audit` requires group administrator rights. Its `--limit` range is 1 through 500, with a default of 100 events. Its repeatable `--user` filter selects action authors. The repeatable `--type` filter accepts exactly these 17 stable grouped event types: `info_changed`, `settings_changed`, `member_joined`, `member_left`, `member_invited`, `member_banned`, `member_unbanned`, `member_restricted`, `member_unrestricted`, `admin_promoted`, `admin_demoted`, `message_deleted`, `message_edited`, `message_pinned`, `invite_changed`, `topic_changed`, and `other`.
+`group audit` requires group administrator rights. Its `--limit` range is 1 through 500, with a default of 100 events. Its repeatable `--user` filter selects action authors. The repeatable `--type` filter accepts these event groups:
+
+- **Chat**: `info_changed`, `settings_changed`
+- **Members**: `member_joined`, `member_left`, `member_invited`, `member_banned`, `member_unbanned`, `member_restricted`, `member_unrestricted`
+- **Administrators**: `admin_promoted`, `admin_demoted`
+- **Messages**: `message_deleted`, `message_edited`, `message_pinned`
+- **Invites and topics**: `invite_changed`, `topic_changed`
+- **Other**: `other`
 
 Inspection and management actions use human-readable output by default; actions that expose `--json` or `--yaml` provide structured success or error output. Failures set a nonzero exit status. They use the current account unless `--account <name>` selects another registered account for that invocation.
 
 Management actions are grouped under `member`, `admin`, `chat`, `invite`, `topic`, and `message`. Member targets must be explicit `@username` values or numeric Telegram user IDs. Durations accept `s`, `m`, `h`, and `d` suffixes, or `off` where disabling is supported. For example, `tg group member mute @team @alice 2h --yes` temporarily mutes a member, while `tg group chat slowmode @team off` disables slow mode.
 
-Potentially destructive CLI actions refuse to connect to Telegram unless `--yes` is present. Permanently deleting a chat additionally requires `--confirm-title` with the exact current title. Interactive listen mode presents these confirmations in an Ink modal. Management requires the relevant administrator permission, and some actions require a supergroup, forum, or creator role. Ownership transfer currently reports `password_required` when Telegram requires a password; this release does not accept a password for that action.
+Potentially destructive CLI actions refuse to connect to Telegram unless `--yes` is present. Permanently deleting a chat additionally requires `--confirm-title` with the exact current title. Interactive listen mode presents these confirmations in an Ink modal. Management requires the relevant administrator permission, and some actions require a supergroup, forum, or creator role.
 
 Use `tg group member info <chat> <user>` as the canonical member-details route. The legacy `tg group member <chat> <user>` form remains available, but a chat name matching a reserved member action such as `ban`, `mute`, or `info` is ambiguous and requires the canonical route.
 
@@ -245,13 +321,22 @@ Interactive `tg listen` presents every supported slash command in one menu. This
 /member mute @alice 2h
 ```
 
-Typing `/` opens the unified command menu, with reply first. Matching ranks exact paths, prefixes, then ordered fuzzy matches, so `/rep` and `/rpy` find `/reply`, while `/ban` finds `/member ban`. Use Up/Down to move through matches. Tab completes the selected command; Enter also completes an incomplete selection, or runs a complete command. Esc closes the menu, result, or confirmation.
+Typing `/` opens the unified command menu, with reply first. Matching ranks exact paths, prefixes, then ordered fuzzy matches, so `/rep` and `/rpy` find `/reply`, while `/ban` finds `/member ban`. Use **Up** and **Down** to move through matches. **Tab** completes the selected command. **Enter** completes an incomplete selection or runs a complete command. **Esc** closes the menu, result, or confirmation.
 
 Group-command availability and permission checks are unchanged: unavailable actions remain disabled, risky actions open a confirmation modal, and chat deletion also asks for the exact title. When listening to more than one chat, set an unambiguous outgoing target with `--send-to <chat>` before using group commands, for example `tg listen @team @ops --send-to @team`.
 
 ## Online and local commands
 
-Online commands connect to Telegram and require a valid session. These include `status`, `whoami`, `chats`, `history`, `sync`, `sync-all`, `refresh`, `info`, all `group` inspection and management families, `send`, `edit`, `delete`, and `listen`.
+Online commands connect to Telegram and require a valid session:
+
+- `read`, `search-online`, and `inbox` return results without storing them locally.
+- `history`, `sync`, `sync-all`, and `refresh` persist fetched messages in SQLite.
+- `contact`, `notification`, `folder`, `info`, and `group` inspect or manage Telegram data.
+- `archive` reads Telegram history and writes Markdown files locally.
+- `send`, `edit`, and `delete` modify Telegram messages.
+- `listen` keeps a connection open for incoming messages and interactive actions.
+
+Global online searches and large archives can trigger Telegram flood waits or other rate limits.
 
 Local commands read or modify the selected account's message database without connecting to Telegram. These include `search`, `recent`, `stats`, `top`, `timeline`, `today`, `filter`, `export`, and `purge`.
 
@@ -284,12 +369,26 @@ Common commands:
 | `tg account current` | Show the current account. |
 | `tg account switch [name]` | Select the default account interactively or set it by name. |
 | `tg account remove <name> --force` | Remove an account and its local session/data. |
+| `tg account logout <name> --yes` / `tg account login <name>` | Confirm logout non-interactively, or reauthenticate interactively into a new local session; local messages are retained. |
 | `tg status` | Check whether the Telegram account is authenticated. |
 | `tg whoami` | Show basic authenticated account information. |
 | `tg config set --api-id <id> --api-hash <hash>` | Save Telegram API credentials for persistent use. |
 | `tg config set --proxy <url>` | Save an optional proxy for account login and Telegram-backed commands. |
-| `tg config list [--show-secrets]` | Show effective configuration values and sources; the proxy URL is always visible. |
-| `tg chats` | List available chats. |
+| `tg config list [--show-secrets]` | Show effective configuration values and sources. Proxy credentials remain masked. |
+| `tg config write-access [status\|on\|off]` | Inspect or gate remote Telegram mutations. |
+| `tg chats [--group\|--channel\|--user]` | List available chats, optionally filtered by type (`--group` includes supergroups). |
+| `tg inbox` | List unread dialogs online without marking messages read. |
+| `tg read <chat> [--since <time>] [--until <time>]` | Read recent Telegram messages without persisting them locally. |
+| `tg search-online <query> [--chat <chat>]` | Search Telegram globally or within one chat without persisting results. |
+| `tg contact list` / `tg contact info <user_or_phone>` | List contacts or resolve one by ID, username, or phone. |
+| `tg dialog inbox` / `tg dialog read <chat>` | Use the dialog-family routes for `inbox` and `read`. |
+| `tg dialog search <query>` / `tg dialog groups` | Search online messages or list group dialogs through the dialog family. |
+| `tg notification info <chat>` | Show notification settings for a chat. |
+| `tg notification mute <chat> [duration]` | Mute notifications temporarily or indefinitely. |
+| `tg notification unmute <chat>` | Restore notifications for a chat. |
+| `tg folder list` / `tg folder info <folder>` | List folders or inspect one folder. |
+| `tg folder chat add <folder> <chat>` | Add an explicit chat to a folder. |
+| `tg folder chat remove <folder> <chat>` | Remove an explicit chat from a folder. |
 | `tg history <chat> -n <limit>` | Fetch and store full chat history (default up to 1000 messages). |
 | `tg sync <chat>` | Incrementally sync new messages for one chat. |
 | `tg sync-all` | Sync messages from all chats, using local last-message IDs for incremental updates. |
@@ -301,12 +400,14 @@ Common commands:
 | `tg recent`, `tg today`, `tg stats`, `tg top`, `tg timeline` | Explore local message data. |
 | `tg filter <keywords>` | Filter local messages by keyword with optional chat/hour filters. |
 | `tg export <chat>` | Export local messages from a chat. |
+| `tg archive <chat ...>` / `tg archive --all` | Archive selected or all chats as incremental Markdown files. |
 | `tg send <chat> [message] [--file <path> ...]` | Send text, files, or a captioned media group. |
 | `tg edit <chat> <msgId> <text>` | Edit a message. |
 | `tg delete <chat> <msgIds...>` | Delete one or more messages. |
 | `tg purge <chat> --yes` | Remove a chat's locally stored messages. |
 | `tg info <chat>` | Show metadata for a Telegram chat. |
 | `tg group info <chat>` | Show read-only group or supergroup details. |
+| `tg group list [--admin]` | List group, supergroup, and channel dialogs; `--admin` keeps only chats you administer or own. |
 | `tg group members <chat> [--type <type>] [--query <text>] [--limit <count>]` | List and filter members (default `recent`, limit 100; maximum 200). |
 | `tg group member <chat> <user>` | Show one member's role, rights, and restrictions. |
 | `tg group audit <chat> [--query <text>] [--user <user>] [--type <type>] [--limit <count>]` | Query the administrator audit log (default 100; maximum 500). |
@@ -314,21 +415,44 @@ Common commands:
 
 All sync-like commands write to local SQLite storage. The `sync-all` and `refresh` commands process multiple chats based on locally stored message IDs.
 
-Many commands support `--json` or `--yaml` for structured output. Failed commands return a nonzero exit code, so scripts can detect errors without parsing human-readable text.
+Finite commands support explicit `--json`, `--yaml`, and `--markdown` output. Without an explicit format, non-interactive output remains YAML. Interactive terminals use rich human-readable output.
+
+Successful finite output is written to stdout. JSON/YAML structured failures are written to stdout in the requested format. Output-format conflicts also use stdout and a stable YAML envelope. Human-readable and Markdown failures are written to stderr. Every failure sets a nonzero exit status.
+
+The `listen` command is an unbounded stream, so these finite-output rules don't apply to it.
 
 Common options:
 
 | Option | Purpose |
 | --- | --- |
 | `--account <name>` | Use a registered account without changing the current account. |
-| `--json` / `--yaml` | Emit structured output when the command supports it. |
+| `--json` / `--yaml` / `--markdown` | Select JSON, YAML, or Markdown output for a finite command. |
 | `-v`, `--verbose` | Enable debug logging. |
 | `-V`, `--version` | Print the installed version. |
 
 Use `tg <command> --help` to inspect command-specific options. For example, `listen` supports reconnection and plain-text modes, while `search` supports sender, time, regular-expression, and result-limit filters.
 
+### Error codes
+
+Structured output exposes stable top-level command errors under `error.code`, with operation-specific details where available:
+
+- **Accounts:** `account_logged_out`, `account_identity_mismatch`, `interaction_required`
+- **Contacts:** `contact_not_found`
+- **Notifications and folders:** `invalid_notification_duration`, `folder_not_found`, `ambiguous_folder`, `folder_operation_unsupported`
+- **Group ownership:** `password_required`, `password_invalid`, `password_too_fresh`, `session_too_fresh`
+- **Archive:** `archive_account_mismatch`, `archive_failed`, `archive_partial_failure`. When an attachment fails but the archive retains partial results, the top-level code is `archive_partial_failure`, the command exits nonzero, and each media warning uses `archive_media_failed` under `error.details.warnings[].code`.
+- **Write safety and rate limits:** `write_access_disabled`, `flood_wait`
+
+### Remote write safety
+
+Run `tg config write-access status` to inspect the current setting. Use `tg config write-access off` to block remote mutations made by send, edit, delete, notification, folder, and group commands. Local database operations, configuration changes, and Telegram reads remain available.
+
+Run `tg config write-access on` to restore remote mutations after testing or maintenance.
+
 ### Sync and listen behavior
 
+These rules describe how synchronization, listening, replies, and downloads affect local data and terminal output.
+
 - `sync-all` and `refresh` are batch operations for local persistence; they are not read-only.
 - `listen` prints a concise separator for each incoming message and can optionally suppress attachment summaries.
 - Telegram media groups appear as one incoming message with a combined attachment summary.
@@ -341,6 +465,8 @@ Use `tg <command> --help` to inspect command-specific options. For example, `lis
 
 ## Troubleshooting
 
+Use these steps to resolve common account, session, and API credential errors.
+
 ### No active account
 
 If a command reports `account_required`, add an account or select an existing one:
@@ -382,8 +508,6 @@ accounts/<name>/messages.db
 
 Treat persisted configuration, `.env`, Telegram credentials, session files, and SQLite data as sensitive. Never share them or commit them to version control.
 
-The `config.json` file may contain an optional `proxy` setting in addition to API credentials. CLI success and error output does not print the stored proxy URL, but you must still protect `config.json`, the environment, and shell history because proxy URLs can contain credentials or MTProxy secrets.
-
 ## Development
 
 This project uses pnpm: