tg-cli

# tg — Telegram CLI via MTProto

CLI tool for reading Telegram data directly via MTProto protocol. No Bot API, no limits.

## Required binaries

| Binary | Install | Purpose |
|---|---|---|
| `tg` | `npm install -g tg-mtproto-cli` | Core CLI |
| `jq` (optional) | `brew install jq` or `apt install jq` | JSON filtering in workflow examples |

Source and provenance:
- npm: [npmjs.com/package/tg-mtproto-cli](https://www.npmjs.com/package/tg-mtproto-cli)
- GitHub: [github.com/cyberash-dev/tg-mtproto-cli](https://github.com/cyberash-dev/tg-mtproto-cli)

Verify after install:

```bash
tg --version
npm ls -g tg-mtproto-cli
```

## Required credentials

| Credential | How to obtain | Storage |
|---|---|---|
| Telegram `api_id` + `api_hash` | [my.telegram.org/apps](https://my.telegram.org/apps) | System keychain (macOS Keychain / Windows Credential Vault / Linux Secret Service) |
| Phone number + OTP code | Interactive prompt during `tg auth` | Not persisted; used once for session creation |

Credentials are entered interactively via `tg auth`. No environment variables required.

## Runtime surface

| Resource | Access | Details |
|---|---|---|
| Network | Outbound TCP to Telegram DC servers | MTProto protocol, required for all commands |
| Session files | Read/write `~/.tg-mtproto-cli/sessions/*.session` | SQLite databases with auth keys; created by `tg auth` |
| System keychain | Read/write | Stores `api_id`, `api_hash`, account metadata, default account |
| Filesystem | Write (only `tg download`) | Saves media to `--out` dir or current directory |

## Guardrails

- The CLI is **read-only by design** — it has no commands to send messages, create chats, modify groups, or perform any write operations on Telegram. The only write targets are local: session files and downloaded media.
- `tg download` writes files only to the explicitly specified `--out` directory or cwd.
- Session files contain sensitive auth material — do not read, copy, or expose `~/.tg-mtproto-cli/sessions/`...