Setup and maintenance
Login, profiles, configuration, the background server, the local store, diagnostics, agent connection and updates.
This reference covers setup and maintenance commands. Use it to look up login, profiles, configuration, the background server, the local store, diagnostics and agent connection.
Login, profiles, configuration, the background server, the local store, diagnostics, agent connection and updates.
Options for every command
| Option | What it does |
|---|---|
-V, --version | output the version number. |
-v, --verbose | more detail in what is shown: -v ids, -vv everything we know. Default: 0. |
--json | machine-readable output: one JSON value on stdout, nothing else. |
--agent-json | JSON for AI agents: invisible controls are visible; ordinary --json preserves text. |
--jsonl | machine-readable output: one JSON object per line, for streaming and jq. |
--quiet | diagnostics off; a failure is still said. |
--trace | the connection's own log lines on stderr — never message content. |
--debug | on a failure, its whole record — cause and stack — in place of the short line. |
--timeout <duration> | give up on the whole command after this — 30s, 2m, 500ms. |
--offline | answer from what was recorded and never connect; fails if nothing was. |
--no-input | never prompt or open interactive login; piped input remains available. |
--max-input-bytes <bytes> | maximum buffered input bytes (default: 16777216). |
--max-output-bytes <bytes> | maximum machine output bytes (default: 4194304; 0 disables). |
--fields <paths> | comma-separated item or object fields: id,text; preserve pagination and operation ids. |
--brief | found messages and mail as reference, title, time, sender and excerpt only. |
--full | found messages and mail with their whole text and every provider field. |
--dry-run | preview parsed arguments and permissions before running the action. |
--yes | go ahead without the question an ask level puts before a write. |
--record | keep this run — ids and timings, never message content. |
--no-record | do not keep it, whatever the configuration says. |
Commands
tg session
log this profile in to Telegram, or out
tg session start
log in by QR code (default) or by phone number, code and 2FA password
tg session start [method] [options]| Argument | Requirement | What it is |
|---|---|---|
method | optional | how to log in. One of: qr, phone. Default: qr. |
| Option | What it does |
|---|---|
--app <how> | the first time only: how to get this profile's app from my.telegram.org. One of: browser, auto. Default: browser. |
--qr-file <png> | write the QR code to this PNG instead of drawing it, for an agent to pass on. |
--sms | phone login: ask Telegram to send the code by SMS, not to the app; Telegram may still refuse. |
tg session end
log this profile out on Telegram's side and forget the session here
Changes something in Telegram.
tg session endtg setup
set up Telegram and connect your agent
Changes something in Telegram.
tg setup [options]| Option | What it does |
|---|---|
--agent <agent> | install the skill for this agent; asks at a terminal, otherwise none. One of: none, codex, cursor, claude, gemini, all. |
--app <how> | how to get your Telegram app credentials the first time. One of: auto, browser. Default: auto. |
--method <method> | how to log in when there is no session. One of: qr, phone. Default: qr. |
--qr-file <png> | write a temporary login QR image for an agent; needs stored app credentials without a terminal. |
tg account
the logged-in account
tg account list
every profile on this computer, and the account each is logged in as; asks the messenger nothing
tg account listtg account show
who this profile is logged in as; the phone number shows its last four digits
tg account show [options]| Option | What it does |
|---|---|
--show-phone | print the whole phone number. |
tg account update
change the name, the description or the photo everyone sees on your profile
Changes something in Telegram.
tg account update [options]| Option | What it does |
|---|---|
--first-name <name> | your first name. |
--last-name <name> | your last name. |
--description <text> | about you. |
--photo <file> | a new profile photo — an image file. |
tg account sessions
where else this account is logged in — not tg session, which is this tool's own login
tg account sessions list
every device and app logged in to this account; nothing is ended
tg account sessions listtg account sessions end
log out every other device, your phone included; this one stays
Changes something in Telegram.
tg account sessions end [options]| Option | What it does |
|---|---|
--others | every session but this one. |
tg models
models that run on this machine
tg models audio
speech models for transcribing voice messages
tg models audio list
the speech models, most suitable first, which are downloaded, and which one is the default
tg models audio listtg models audio download
download a speech model once, checked against the sha256 this version expects
tg models audio download <model>tg models text
embedding models for searching conversations by meaning
tg models text list
the embedding models, most suitable first, which are downloaded, and which one is the default
tg models text listtg models text download
download an embedding model once, checked against the sha256 this version expects
tg models text download <model> [options]| Option | What it does |
|---|---|
--accept-terms | accept the model's licence terms, for a model that has its own. |
tg models text key
API keys for embedding and analysis providers
tg models text key set
store a key, typed at a hidden prompt or piped on stdin — never as an argument
tg models text key set <provider>| Argument | Requirement | What it is |
|---|---|---|
provider | required | openai, anthropic, or the host of a --base-url server that wants a key. |
tg models text key remove
forget a stored key
tg models text key remove <provider>| Argument | Requirement | What it is |
|---|---|---|
provider | required | openai, anthropic, or a server's host. |
tg watch
print new messages as they arrive, until Ctrl-C or --timeout (either ends it normally)
tg watch [options]| Option | What it does |
|---|---|
--events | also edits, deletions and reactions; every line then names its event. |
tg serve
keep the local store current until stopped — what a systemd or launchd unit runs
tg servetg server
tg serve in the background: start, stop, restart, status, logs; install adds a systemd or launchd unit
tg server start
start serve in the background — through the unit if one is installed — and answer once it connects
tg server starttg server stop
stop this profile's serve — through the unit if it runs under one
tg server stoptg server restart
stop it and start it again
tg server restarttg server status
whether serve runs for this profile, since when, who started it, and the unit if there is one
tg server statustg server logs
serve's latest log lines — from the journal under systemd, else its log file
tg server logs [options]| Option | What it does |
|---|---|
-n, --lines <n> | how many lines. Default: 50. |
tg server install
write a systemd user unit or a launchd agent for this profile; starts nothing
tg server installtg server uninstall
remove this profile's unit; stop it first
tg server uninstalltg store
the local store of messages
tg store status
per chat: messages stored, the oldest and newest, and the stretches held completely
tg store status [chat]| Argument | Requirement | What it is |
|---|---|---|
chat | optional | a chat: its title or part of it, its id, @username, or me for Saved Messages. |
tg store gaps
inspect recorded interior coverage gaps and explicitly fetch them
tg store gaps plan
local coverage plan; missing message ids alone do not imply missing history
tg store gaps plan <chat>| Argument | Requirement | What it is |
|---|---|---|
chat | required | a chat: its title or part of it, its id, @username, or me for Saved Messages. |
tg store gaps repair
fetch bounded interior gaps and recheck coverage; never delete unseen messages
tg store gaps repair <chat> [options]| Argument | Requirement | What it is |
|---|---|---|
chat | required | a chat: its title or part of it, its id, @username, or me for Saved Messages. |
| Option | What it does |
|---|---|
--limit <n> | total messages in this repair, 500 by default. |
--max-gaps <n> | at most this many gaps, 5 by default. |
--repair-time <duration> | time budget for the repair, 30s by default. Default: 30s. |
--page-size <n> | messages per provider page. |
--pause <duration> | provider pause between pages. Default: 1s. |
--fingerprint <hash> | refuse if this previously inspected coverage plan changed. |
--catch-up | prepare local search after repair; overrides searchCatchUp. |
--no-catch-up | skip local search preparation after repair. |
--catch-up-chunks <n> | maximum local chunks prepared. |
--catch-up-messages <n> | maximum stored messages read for preparation. |
--catch-up-time <duration> | preparation time within the repair's remaining budget. |
--background | repair as an existing store job; inspect store jobs show. |
tg store jobs
background sync jobs
tg store jobs list
background sync jobs, newest first
tg store jobs list [options]| Option | What it does |
|---|---|
--state <state> | only jobs in this state. One of: running, done, partial, failed, cancelled, died. |
tg store jobs show
one background job — the newest when none is named — and what the store now holds of its chat
tg store jobs show [job]tg store jobs cancel
stop a running background job after its current page; a later sync resumes where it stopped
tg store jobs cancel <job>| Argument | Requirement | What it is |
|---|---|---|
job | required | the job id. |
tg store jobs retry
start a partial, failed or died job again, as a new job; the sync resumes where the store stopped
tg store jobs retry [job] [options]| Argument | Requirement | What it is |
|---|---|---|
job | optional | the job id. |
| Option | What it does |
|---|---|
--failed | every chat whose newest job partial, failed or died. |
tg store jobs clear
forget finished jobs and remove their logs; a running job is kept
Changes something on this computer only.
tg store jobs cleartg store export
a chat's stored messages, oldest first: --jsonl one message per line, --json one { items, page, limit, hasMore } object; never asks the messenger
tg store export [chats] [options]| Argument | Requirement | What it is |
|---|---|---|
chats | optional | a chat: its title or part of it, its id, @username, or me for Saved Messages; several with --to. |
| Option | What it does |
|---|---|
--format <format> | jsonl: one message per line, the default with --output; markdown: a transcript with a heading per day, replies and forwards quoted. |
--since-time <time> | only from this ISO 8601 time, or 30m / 2h / 1d ago, on. |
--output <file> | write JSON lines, or the transcript, to this new file, readable only by you. |
--to <dir> | write into this folder, a file per chat and a manifest; run again on it for only what changed since. |
--kind <kinds> | with --to: every stored chat of these kinds, comma-separated: dialog, group, channel, saved. |
--all | with --to: every stored chat of this account. |
--encrypt | compress and encrypt with a password, typed at a hidden prompt or piped on stdin; it is never kept — lose it and the file cannot be opened. |
tg store clear
delete from the store the chats this account has left, with their messages
tg store clear [options]| Option | What it does |
|---|---|
--left | the chats this account has left — the only thing this clears. |
--allow-dangerous | yes, delete — it cannot be undone, and a chat you left cannot be fetched again. |
tg store info
the store file: where it is, its size, its schema and how many rows it holds; changes nothing
tg store infotg store check
whether the store is healthy — integrity, search indexes, disk, and which chats are behind
tg store checktg store migrate
bring the store up to this build's schema, then normalize, index and stem the messages and notes stored before it
tg store migratetg store reindex
rebuild the word index, its typo vocabulary, the stems, the files' word index, the notes' indexes and who took part in what, from what is stored; loses nothing
tg store reindextg store backup
copy the store into a new file, while it is in use; never overwrites a file
tg store backup <file> [options]| Argument | Requirement | What it is |
|---|---|---|
file | required | the new file. |
| Option | What it does |
|---|---|
--encrypt | compress and encrypt with a password, typed at a hidden prompt or piped on stdin; it is never kept — lose it and the file cannot be opened. |
tg store restore
put a backup in place of the store; the store it replaces is kept beside it, never deleted
tg store restore <file>| Argument | Requirement | What it is |
|---|---|---|
file | required | a file store backup wrote; one written with --encrypt asks for its password. |
tg store decrypt
open a file written with --encrypt into a new file; asks for its password
tg store decrypt <file> [options]| Argument | Requirement | What it is |
|---|---|---|
file | required | a file store backup --encrypt or store export --encrypt wrote. |
| Option | What it does |
|---|---|
--output <file> | the new file, readable only by you. |
tg store repair
bring every table to this build's shape, deleting nothing: a table of the wrong shape is kept as a copy beside a new one
tg store repair [options]| Option | What it does |
|---|---|
--dry-run | say what it would do, and change nothing. |
tg store reset
back the store up beside itself, then delete it and start an empty one at this build's schema; asks first, or --yes
tg store reset [options]| Option | What it does |
|---|---|
--no-backup | delete the store without backing it up first. |
tg store copies
the tables store repair kept as copies
tg store copies delete
delete one copy store repair kept, named exactly; refuses any other table
tg store copies delete <name>tg flood
the waits Telegram asked this profile to keep, and a hold on its writes
tg flood clear
forget them, lift the hold and the profile's pace, once Telegram no longer limits the account; changes nothing there
tg flood cleartg runs
recorded runs — what this tool did, and when
tg runs list
recorded runs, newest first
tg runs list [options]| Option | What it does |
|---|---|
--limit <n> | how many to show. Default: 20. |
tg runs show
one run: what it was, how it ended and what went wrong; -v for every event
tg runs show <run-id>tg runs search
search recorded diagnostic metadata and events; no message contents
tg runs search [query] [options]| Argument | Requirement | What it is |
|---|---|---|
query | optional | case-insensitive literal diagnostic text. |
| Option | What it does |
|---|---|
--status <status> | run outcome. One of: success, failed, partial, running. |
--error-code <code> | one stable error code. |
--operation <name> | one operation, such as messages.download. |
--profile <name> | one recorded profile. |
--since-time <time> | runs starting on or after an ISO time or 2h / 1d ago. |
--limit <n> | matches per page, at most 100. Default: 20. |
--page <n> | result page. Default: 1. |
tg runs path
the directory holding one run
tg runs path <run-id>tg config
the settings in force, and where each one came from
tg config migrate
replace legacy access settings with permissions, preserving this file's effective levels
Changes something on this computer only.
tg config migrate [options]| Option | What it does |
|---|---|
--dry-run | show the migration without writing the file. |
tg config show
the profile, the profiles that exist, and each setting with where it came from
tg config show [options]| Option | What it does |
|---|---|
--bot | the settings a bot command on this profile gets, rather than the personal account's. |
tg config set
save a setting to the configuration file
Changes something on this computer only.
tg config set <setting> <value> [options]| Argument | Requirement | What it is |
|---|---|---|
setting | required | one of: limit, timeoutMs, color, senderColors, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, requestsPerMinute, transcribeWith, speechModel, catchUpMarksRead, searchCatchUp, embeddingProvider, embeddingModel, embeddingBaseUrl, embeddingDims, analysisProvider, analysisModel, analysisBaseUrl, models, proxy, readOtherBots, updateCheck, skillHint, defaultProfile, searchStemmers.cyrillic, searchStemmers.latin, accountGroups.. |
value | required | a number, true or false, or for allow a list like send,reaction; for a group tg:work,max:Alice,email:me@x. |
| Option | What it does |
|---|---|
--defaults | change what every profile gets, rather than this profile. |
--personal | only for personal accounts — the personal section of the file. |
--bot | only for bots — the bot section of the file. |
tg config unset
remove a setting from the configuration file
Changes something on this computer only.
tg config unset <setting> [options]| Argument | Requirement | What it is |
|---|---|---|
setting | required | one of: limit, timeoutMs, color, senderColors, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, requestsPerMinute, transcribeWith, speechModel, catchUpMarksRead, searchCatchUp, embeddingProvider, embeddingModel, embeddingBaseUrl, embeddingDims, analysisProvider, analysisModel, analysisBaseUrl, models, proxy, readOtherBots, updateCheck, skillHint, defaultProfile, searchStemmers.cyrillic, searchStemmers.latin, accountGroups.. |
| Option | What it does |
|---|---|
--defaults | change what every profile gets, rather than this profile. |
--personal | only for personal accounts — the personal section of the file. |
--bot | only for bots — the bot section of the file. |
tg doctor
the state this installation is in, without connecting unless --online
tg doctor [options]| Option | What it does |
|---|---|
--online | also connect once and read the account; sends nothing. |
tg doctor report
what a problem report holds; writes nothing
tg doctor report create
write a problem report to a file, and say where to send it
tg doctor report create [options]| Option | What it does |
|---|---|
--run <id> | the run the report is about; the newest failed one if not given. |
--output <file> | where to write it; a new file in this directory if not given. |
tg commands
commands, options and exit codes as JSON — inspect one command path per call
tg commands schema
one command's argv and result schemas, effects, permissions and retry guidance
tg commands schema <path>| Argument | Requirement | What it is |
|---|---|---|
path | required | one command path, for example: stats messages show. |
tg complete
shell completion: tg complete zsh prints the script to source
tg complete [words]| Argument | Requirement | What it is |
|---|---|---|
words | optional |
tg upgrade
upgrade tg with the package manager that installed it; --check only looks
tg upgrade [options]| Option | What it does |
|---|---|
--check | say whether a newer version exists, and install nothing. |
tg mcp
serve this profile to an agent over MCP, on stdin and stdout — claude mcp add tg -- tg mcp
tg mcp [options]| Option | What it does |
|---|---|
--permission <key=level> | override a permission for this server only; repeat for more keys. |
--confirm-send | no longer used — writes show no form; the profile's permissions decide. |
--allow-dangerous | no longer used — writes show no form; the profile's permissions decide. |
--allow-send | no longer used — the profile's permissions decide; kept so an old setup still starts. |
--allow-mark-read | no longer used — the profile's permissions decide. |
--allow-delete | no longer used — the profile's permissions decide. |
--http | serve over HTTP on 127.0.0.1 for ChatGPT and Claude in the browser, behind your tunnel; the profile's permissions decide. |
--http-confirmation <mode> | no longer used — writes show no form; the profile's permissions decide. |
--port <port> | the local port for --http (default 8765). |
--public-url <url> | the tunnel's https address the browser apps use, e.g. https://.ts.net. |
--revoke | forget every login given to a browser app; each must log in again. |
tg mcp config
print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing
tg mcp config [options]| Option | What it does |
|---|---|
--permission <key=level> | override a permission for this server only; repeat for more keys. |
--confirm-send | no longer used — writes show no form; the profile's permissions decide. |
--allow-dangerous | no longer used — writes show no form; the profile's permissions decide. |
--allow-send | no longer used — the profile's permissions decide; kept so an old setup still starts. |
--allow-mark-read | no longer used — the profile's permissions decide. |
--allow-delete | no longer used — the profile's permissions decide. |
tg mcp setup
add this profile's local MCP server to Codex or Claude Code
Changes something on this computer only.
tg mcp setup <client> [options]| Argument | Requirement | What it is |
|---|---|---|
client | required | codex or claude-code. |
| Option | What it does |
|---|---|
--allow-writes | acknowledge that this profile offers writing tools. |
--permission <key=level> | override a permission for this server only; repeat for more keys. |
--confirm-send | no longer used — writes show no form; the profile's permissions decide. |
--allow-dangerous | no longer used — writes show no form; the profile's permissions decide. |
--allow-send | no longer used — the profile's permissions decide; kept so an old setup still starts. |
--allow-mark-read | no longer used — the profile's permissions decide. |
--allow-delete | no longer used — the profile's permissions decide. |
tg mcp doctor
check this profile's local MCP handshake and tool list
tg mcp doctor [options]| Option | What it does |
|---|---|
--permission <key=level> | override a permission for this server only; repeat for more keys. |
--confirm-send | no longer used — writes show no form; the profile's permissions decide. |
--allow-dangerous | no longer used — writes show no form; the profile's permissions decide. |
--allow-send | no longer used — the profile's permissions decide; kept so an old setup still starts. |
--allow-mark-read | no longer used — the profile's permissions decide. |
--allow-delete | no longer used — the profile's permissions decide. |
tg skill
the instructions an agent is given for this tool
tg skill show
print SKILL.md — tg skill install puts it where Claude Code, Codex and Gemini CLI look for it
tg skill show [name]| Argument | Requirement | What it is |
|---|---|---|
name | optional | one of the skills shipped for a task: follow-ups, link-conversations. |
tg skill install
write SKILL.md to ~/.claude/skills/tg-cli/ (Claude Code) and ~/.agents/skills/tg-cli/ (Codex, Gemini CLI)
tg skill install [options]| Option | What it does |
|---|---|
--for <agents> | which agents to install for. One of: claude, agents, all. Default: all. |
Exit codes
Branch on the code, not on the text: the text can change, the code does not.
| Code | When |
|---|---|
0 | it worked |
2 | validation_error |
3 | configuration_error |
4 | authentication_error |
5 | permission_error |
6 | not_found |
7 | confirmation_required |
8 | rate_limited |
9 | timeout |
10 | network_error |
11 | provider_error |
12 | provider_unavailable |
13 | invalid_response |
14 | outcome_unknown |
130 | cancelled |
1 | anything else |
0 and only 0 means the operation was done. 14 (outcome_unknown) means a message may
have gone: repeat it only with the same --send-id, which Telegram uses to drop a second copy.