grammpars 0.1.0

Offline conversion between Telegram Desktop tdata, Telethon, and grammers sessions
Documentation

grammpars

grammpars converts local Telegram authorization sessions between Telegram Desktop tdata, Telethon SQLite (schema 8), and grammers SQLite (schema 1). It is available as both a Rust library and a command-line program.

The converter is fully offline: it does not connect to Telegram and does not need an API ID or API hash. Session files contain an authorization key and must be protected like a password. This project is not affiliated with Telegram.

usage guide · format notes · security policy

source repository · issue tracker

Capabilities

  • Read modern password-protected and unprotected Telegram Desktop tdata.
  • Export any loaded account to a Telethon or grammers session.
  • Import a Telethon or grammers session into a new Telegram Desktop tdata.
  • Validate TDF checksums, encrypted payloads, DC IDs, key lengths, and SQLite schemas before accepting credentials.
  • Redact credentials from debug output and zeroize owned key/passcode buffers when they are dropped.
  • Write output through temporary files so an interrupted conversion does not normally destroy an existing session.
  • Run on Linux, macOS, and Windows; SQLite is bundled.

Only production DCs 1 through 5 are supported. The crate does not log in, migrate an account between DCs, discover a user ID, or support Telegram test servers.

Installation

The minimum supported Rust version is 1.74.

[dependencies]
grammpars = "0.1"

Install the CLI after publication with:

cargo install grammpars

Command line

Export account slot 0 from tdata:

grammpars export --tdata ./tdata --format telethon --output account.session

Import a session. Telegram's numeric user ID is required because ordinary SQLite session files do not store it:

grammpars import --session account.session --format telethon \
  --user-id 123456789 --output ./new-tdata

For a locally password-protected tdata, put the password in an environment variable instead of a command-line argument:

GRAMMPARS_PASSCODE='local password' grammpars export \
  --tdata ./tdata --format grammers --output account.session

The variable name defaults to GRAMMPARS_PASSCODE and can be changed with --passcode-env. Import refuses a non-empty destination unless --force is passed. Make a backup and close Telegram Desktop before replacing live data.

Library

use grammpars::{Result, SessionFormat, TDesktop};

fn main() -> Result<()> {
    let mut desktop = TDesktop::new("./tdata")?;
    desktop.load_tdata()?;
    desktop.export_session("account.session", SessionFormat::Telethon, 0)?;
    Ok(())
}

To import and protect the generated tdata with a local password:

use grammpars::{Result, SessionFormat, TDesktop};

fn main() -> Result<()> {
    let desktop = TDesktop::import_session(
        "account.session",
        SessionFormat::Telethon,
        123_456_789,
        "./new-tdata",
    )?
    .with_passcode("local password");
    desktop.save_tdata()?;
    Ok(())
}

Compatibility and verification

The binary layout follows Telegram Desktop's TDF container and local-key derivation, Telethon schema version 8, and grammers schema version 1. Tests cover encrypted round trips, malformed input, checksums, both SQLite formats, and large randomized codec inputs. CI runs formatting, Clippy, documentation, packaging, the Rust 1.74 MSRV, and tests on Linux, macOS, and Windows.

Before publishing a release, follow the release checklist.

License

Licensed under either Apache-2.0 or MIT, at your option.