tmgc CLI spec (v1)

This spec defines the CLI surface, output contract, and minimal behavior. It favors stable machine output (--output table|plain|json|ndjson) and explicit schema/describe paths for automation.

Global

Usage:

tmgc [global flags] <command> [args]

Global flags:

--config <path>: config file path (default: ~/.config/tmgc/profiles/<profile>/config.json)
--profile <name>: profile name (default: default)
--timeout <dur>: request timeout (default: 15s)
--output <table|plain|json|ndjson>: explicit output mode
--json: JSON output
--plain: line-oriented output (TSV)
--describe: print the current command schema and exit
--no-color: disable colors

Environment overrides:

TMGC_API_ID
TMGC_API_HASH
TMGC_SESSION_STORE (keyring or file)

Config storage:

Config: ~/.config/tmgc/profiles/<profile>/config.json
Session: stored in OS keychain when available (default). If keychain is unavailable or session_store=file, fall back to ~/.config/tmgc/profiles/<profile>/session.json (unencrypted).
Peer cache: ~/.config/tmgc/profiles/<profile>/peers.json

Output

Table (default): tabular output on stdout.
Plain (--plain): stable TSV on stdout (tabs preserved), ideal for piping.
JSON (--json): structured JSON on stdout.
NDJSON (--output ndjson): one JSON object per line, ideal for streaming.
Progress/warnings go to stderr.

Peer references

Accepted peer inputs:

u<id>: user (e.g., u123456)
c<id>: chat (group) (e.g., c123456)
ch<id>: channel / supergroup (e.g., ch123456)
@username, t.me/username, tg://resolve?domain=...
phone number (E.164 or with separators)

Auth

tmgc auth login defaults to QR login (fastest, safest). Code login is supported as a fallback for accounts that cannot scan a QR.

Notes:

Telegram may choose non-SMS code types (app, email, Fragment, etc.).
If 2FA is enabled, a password prompt appears after code entry.
QR codes expire quickly; the CLI will refresh and re-print when needed.

Commands

`auth`

tmgc auth login [--method qr|code] [--phone ...] [--api-id ...] [--api-hash ...] [--bot-token ...]
tmgc auth login [--qr-file /path/to/qr.png]
tmgc auth status
tmgc auth logout
tmgc auth config set --api-id ... --api-hash ...
tmgc auth config show
tmgc schema [command]

auth login outputs an AuthStatus JSON object or a summary table.

`chat`

tmgc chat list [--limit 50]
tmgc chat history <peer> [--limit 20] [--since RFC3339]
tmgc chat watch [peer] [--since RFC3339] [--limit N]
tmgc chat info <peer>
tmgc chat pin <peer> <message-id> [--silent] [--pm-oneside]
tmgc chat unpin <peer> <message-id> [--silent] [--pm-oneside]

`chat list`

Output (JSON):

[
  {
    "peer_id": 123456,
    "peer_ref": "u123456",
    "peer_type": "user",
    "title": "Jane Doe",
    "username": "jane",
    "unread_count": 2,
    "last_message_id": 9876,
    "pinned": false
  }
]

`chat history`

Output (JSON):

[
  {
    "id": 42,
    "date": "2026-01-03T20:15:00Z",
    "text": "hello",
    "from_peer_id": 123456,
    "peer_id": 123456,
    "out": true,
    "service": false
  }
]

`message`

tmgc message send <peer> <text> [--reply <id>] [--silent]
tmgc message send <peer> --file <path> [--caption "text"] [--reply <id>] [--silent]
tmgc message send <peer> --file <path> --voice [--reply <id>] [--silent]
tmgc message send <peer> ... --schedule <when>
tmgc message send --input-json '{"peer":"@username","text":"hello"}' --dry-run
tmgc message reply <peer> <reply-to-id> [text]
tmgc message edit <peer> <message-id> <text>
tmgc message delete <peer> <message-id>...
tmgc message forward <from-peer> <message-id>... --to <peer>
tmgc message react <peer> <message-id> [reaction...]
tmgc message info <peer> <message-id>

Output (JSON):

{
  "ok": true,
  "message_id": 123,
  "updates_type": "*tg.Updates"
}

`contact`

tmgc contact list [--limit 20]
tmgc contact info <peer>
tmgc contact search <query> [--limit 20]

Searches synced contacts by display name or username (case-insensitive partial match).

Output (JSON):

[
  {
    "display_name": "Jane Doe",
    "username": "@janedoe",
    "user": "u123456"
  }
]

`search`

tmgc search messages <query> [--chat <peer>] [--limit 20]

Output shape matches chat history.

`file`

tmgc file download <peer> <message-id> [--dest <path>] [--threads N] [--verify]
tmgc file info <peer> <message-id>

file download writes to stdout only for dry-run and machine output; the actual file is written to disk.

Scope

v1 is scoped to:

Auth (QR + code), status, logout
Chat list, history, watch, info, pin, unpin
Message send, reply, edit, delete, forward, react, info
Contact list, info, search
File download and file info
Search messages (global or per chat)

Non-goals for v1:

Full offline sync
Multi-account token management beyond profiles