Telegram CLI

Verwendung der Telegram CLI

Überblick

Verwenden Sie tg als account-bewussten Telegram-Client und lokalen SQLite-Nachrichtenindex. Wählen Sie Befehle basierend auf Datenquelle, Persistenz und danach aus, ob sie Telegram verändern.

Zwingende Regeln

• Fordern Sie vor dem Aktivieren von Schreibzugriff oder dem Ausführen einer entfernten Mutation explizit die Benutzerautorisierung an. Die Autorisierung zum Aktivieren von Schreibzugriff ist keine Autorisierung für eine Mutation. Mehrere Mutationen haben keine eingebaute Bestätigung.
• Überprüfen Sie vor einer geplanten Mutation tg config write-access status --json. Die Sperre gilt nur für entfernte Mutationen; schreibgeschützte Telegram-Aufrufe, lokale SQLite/Datei-Operationen, Account-Lebenszyklus und Konfiguration bleiben verfügbar, während sie deaktiviert ist.
• Geben Sie niemals ein Passwort für einen Besitzerwechsel im Klartext an, fordern Sie es nicht dazu auf und automatisieren Sie es nicht. group admin transfer-owner fordert es nach --yes sicher in einem interaktiven TTY an; es ist nicht für nicht-interaktive CI geeignet.
• Behandeln Sie API-Hashes, Proxy-URLs, Sitzungen, Account-Metadaten, exportierte Nachrichten und Datenbanken als Geheimnisse. Geben Sie niemals config list --show-secrets aus, legen Sie einen Proxy mit Anmeldeinformationen offen oder committen Sie DATA_DIR.
• Wählen Sie ein Konto in der Automatisierung explizit mit --account <name> aus. Ändern Sie nicht das aktuelle Konto, nur um einen Befehl auszuführen.
• Wählen Sie für endliche Befehle genau eines von --json, --yaml oder --markdown aus. Verwenden Sie JSON oder YAML für die Automatisierung und stabile ok/error-Felder; Markdown ist für Menschen gedacht und kann strukturierte Fehlerdetails auslassen. Die Nicht-TTY-Ausgabe verwendet standardmäßig YAML. listen schließt diese Flags aus.
• Überprüfen Sie den Prozess-Exit-Status und das strukturierte ok. Verwenden Sie für die automatisierte Teilfehler-Buchführung bei Archiven JSON/YAML und inspizieren Sie error.code sowie error.details.completed, error.details.failed und error.details.warnings; melden Sie niemals vollständigen Erfolg, wenn ein Chat oder Medium fehlgeschlagen ist.
• Strukturierte Umschläge verwenden schema_version: "2". Nachrichten-Zeilen enthalten content, reply_to_msg_id, media_group_id und geordnete kleingeschriebene attachments[]; erwarten Sie kein altes einzelnes attachment oder rohe Parser-Felder.

Stellen Sie sicher, dass die ausführbare Datei verfügbar ist

Überspringen Sie bei der Entwicklung oder dem Testen des aktuellen Quellcodes dieses Repositorys die globale Paketinstallation. Erfordert Node.js 22 oder höher, führen Sie pnpm install aus und verwenden Sie pnpm dev <args>, z. B. pnpm dev search --help. Fügen Sie kein zusätzliches -- ein; pnpm dev -- search ... übergibt dieses Token an die CLI und kann fehlschlagen.

Für jede andere benutzerangeforderte tg-Aufgabe führen Sie zuerst command -v tg aus. Wenn der Benutzer nur nach Anweisungen fragt, erklären Sie die Einrichtung, ohne sein System zu ändern.

Wenn tg installiert ist, installieren oder aktualisieren Sie es nicht automatisch. Überprüfen Sie die installierte ausführbare Datei und inspizieren Sie die Live-Hilfe:

tg --version
tg --help
tg <command> --help

Wenn tg fehlt, überprüfen Sie zuerst die Laufzeitumgebung:

node --version
npm --version

Fahren Sie nur fort, wenn beide Befehle erfolgreich sind und Node.js Version 22 oder höher ist. Wenn Node.js fehlt oder zu alt ist, verwenden Sie einen vorhandenen, vom Benutzer verwalteten Versionsmanager, falls verfügbar; fragen Sie vor der Installation oder Änderung einer systemweiten Laufzeit oder eines Paketmanagers.

Installieren Sie das veröffentlichte Paket und fahren Sie dann mit der ursprünglichen Aufgabe fort:

npm install --global @will-17173/telegram-cli

Wiederholen Sie einen Berechtigungsfehler niemals mit sudo. Bevorzugen Sie eine vorhandene, vom Benutzer verwaltete Node.js-Installation; andernfalls installieren Sie es in ein benutzereigenes Präfix für die aktuelle Shell:

npm install --global --prefix "$HOME/.local" @will-17173/telegram-cli
export PATH="$HOME/.local/bin:$PATH"

Ändern Sie keine Shell-Startdatei ohne Autorisierung. Stellen Sie nach der Installation sicher, dass diese Prüfungen erfolgreich sind, bevor Sie Telegram-Befehle ausführen:

hash -r
command -v tg
tg --version
tg --help

Wenn die Binärdatei immer noch fehlt, überprüfen Sie das npm-Globalpräfix und PATH, melden Sie den Fehler und stoppen Sie, bevor Sie Telegram-Befehle ausführen.

Wählen Sie die Operation

Bedarf	Befehlsfamilie	Netzwerk	Nebenwirkung
Authentifizieren/Auswählen/Abmelden von Konten	account	login/logout	Sitzung/Registry; Nachrichten bleiben bei Ab-/Anmeldung erhalten
Übersicht über ungelesene oder flüchtige Online-Lesevorgänge	inbox, read, search-online	ja	keine; inbox markiert Nachrichten nicht als gelesen
Kontakte/Chats/Gruppen entdecken	contact, chats, info, group list	ja	keine
Telegram-Verlauf persistieren	history, sync, sync-all, refresh	ja	schreibt lokale SQLite-Datenbank
Chats als Markdown archivieren	archive	ja	schreibt account-lokale Archivdateien
Gespeicherte Nachrichten abfragen/exportieren	search, recent, today, stats, top, timeline, filter, export	nein	Export kann eine Datei schreiben
Lokale Daten nach bahnbrechenden Storage-Upgrades zurücksetzen	data reset	nein	löscht Account-DB/Standard-Archivdateien
Benachrichtigungen oder Ordner inspizieren/ändern	notification, folder	ja	mute/unmute und folder chat add/remove ändern Telegram
Eingehende Nachrichten überwachen	listen	ja, langlebig	persistiert normalisierte Anhänge; optionale Downloads
Telegram-Status ändern	send, edit, delete, notification/folder/group Schreibvorgänge	ja	echter externer Schreibvorgang

Lesen Sie references/command-reference.md, bevor Sie einen genauen Befehl zusammenstellen, die Automatisierungsausgabe verarbeiten, Gruppen verwalten oder Authentifizierungs- und Flood-Limits beheben.

Arbeitsablauf

1. Führen Sie die entsprechende --help aus; bevorzugen Sie sie gegenüber auswendig gelernten Flags.
2. Für account-abhängige Arbeit inspizieren Sie tg account list --json und verwenden Sie ein explizites Konto.
3. Leiten Sie nach Quelle und Persistenz: search verwendet synchronisierte SQLite; search-online und flüchtiges read verwenden Telegram; history/sync persistieren in SQLite. Kopieren Sie keine read-Zeitflags zu history/sync, die Limit/Verzögerungs-Steuerungen verwenden.
4. Behandeln Sie inbox als schreibgeschützte Erkundung; gehen Sie niemals davon aus, dass es Nachrichten als gelesen markiert.
5. Lösen Sie Chats mit chats --json und Ordner mit folder list --json auf; bevorzugen Sie numerische IDs nach der Erkennung, da Namen/Titel mehrdeutig sein können.
6. Parsen Sie strukturierte Umschläge anstelle von Terminal-Tabellen. Verwenden Sie bei Batch-Synchronisationsfehlern refresh und inspizieren Sie data.failures; sync-all lässt dieses Feld aus.
7. Überprüfen Sie unmittelbar vor einem entfernten Schreibvorgang das Ziel, den Schreibzugriffsstatus und holen Sie eine explizite Autorisierung für diese Mutation ein.

Häufige Fehler

• pnpm dev -- ...: Entfernen Sie das zusätzliche Trennzeichen.
• Annahme, dass sync --limit 5000 einen neuen Chat auffüllt: Erste Synchronisation ist auf 500 begrenzt; verwenden Sie history für tiefere Verläufe.
• Erwartung, dass sync-all Teilfehler anzeigt: Verwenden Sie refresh und inspizieren Sie data.failures.
• Wiederverwendung einer alten Datenbank nach einer bahnbrechenden Media-Schema-Änderung: Führen Sie tg data reset --yes aus und synchronisieren Sie erneut.
• Erwartung, dass listen --no-media Persistenz/Downloads unterdrückt: Es blendet nur gerenderte Media-Zeilen aus; normalisierte attachments[] bleiben persistiert und nutzbar.
• Verwendung eines mehrdeutigen Chat-Namens: Wiederholen Sie den Vorgang mit seiner numerischen Chat-ID.
• Verwendung von Markdown für die Archiv-Automatisierung: Es bewahrt keine vollständigen Teilfehlerdetails; verwenden Sie JSON/YAML.
• Übergabe eines 2FA-Passworts in Argumenten, Umgebungsvariablen, stdin-Automatisierung, Chat oder Logs: Besitzerwechsel akzeptiert nur seine sichere interaktive Eingabeaufforderung.
• Erwartung, dass send sofort in der lokalen Suche erscheint: Synchronisieren Sie danach.