# Usage guide
`grammpars` is an offline converter for local Telegram sessions. It supports
Telegram Desktop `tdata`, Telethon SQLite schema 8, and grammers SQLite schema
1 through both a Rust API and a cross-platform command-line interface.
A session contains a Telegram authorization key. Treat `tdata` and `.session`
files like passwords: do not commit them, attach them to issue reports, or send
them to other people. Revoke a compromised session from an official Telegram
client. This project is not affiliated with Telegram and never connects to its
servers.
## Capabilities and limits
- Read password-protected and unprotected `tdata` directories.
- Export a selected account to Telethon or grammers.
- Import a Telethon or grammers session into a new `tdata` directory.
- Validate checksums, sizes, DC identifiers, keys, and SQLite schemas.
- Run on Linux, macOS, and Windows with Rust 1.74 or newer.
Production DCs 1 through 5 are supported. The library does not log in, discover
a user ID over the network, migrate accounts between DCs, or support test DCs.
## Command-line interface
```console
grammpars export --tdata ./tdata --format telethon --output account.session
grammpars import --session account.session --format grammers \
--user-id 123456789 --output ./new-tdata
```
Pass a local password through an environment variable so it does not appear in
the shell history:
```console
GRAMMPARS_PASSCODE='local password' grammpars export \
--tdata ./tdata --format telethon --output account.session
```
Use `--passcode-env` to select a different variable. Import refuses to write to
a non-empty directory unless `--force` is present. Close Telegram Desktop and
create a backup before replacing live data.
## Rust API
```rust,no_run
use grammpars::{Result, SessionFormat, TDesktop};
fn main() -> Result<()> {
let mut desktop = TDesktop::new("./tdata")?.with_passcode("local password");
desktop.load_tdata()?;
desktop.export_session("account.session", SessionFormat::Telethon, 0)?;
Ok(())
}
```
See [FORMAT.md](FORMAT.md) for the format and compatibility contract.