TelegramCommands

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

OptionWhat it does
-V, --versionoutput the version number.
-v, --verbosemore detail in what is shown: -v ids, -vv everything we know. Default: 0.
--jsonmachine-readable output: one JSON value on stdout, nothing else.
--agent-jsonJSON for AI agents: invisible controls are visible; ordinary --json preserves text.
--jsonlmachine-readable output: one JSON object per line, for streaming and jq.
--quietdiagnostics off; a failure is still said.
--tracethe connection's own log lines on stderr — never message content.
--debugon 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.
--offlineanswer from what was recorded and never connect; fails if nothing was.
--no-inputnever 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.
--brieffound messages and mail as reference, title, time, sender and excerpt only.
--fullfound messages and mail with their whole text and every provider field.
--dry-runpreview parsed arguments and permissions before running the action.
--yesgo ahead without the question an ask level puts before a write.
--recordkeep this run — ids and timings, never message content.
--no-recorddo 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]
ArgumentRequirementWhat it is
methodoptionalhow to log in. One of: qr, phone. Default: qr.
OptionWhat 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.
--smsphone 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 end

tg setup

set up Telegram and connect your agent

Changes something in Telegram.

tg setup [options]
OptionWhat 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 list

tg account show

who this profile is logged in as; the phone number shows its last four digits

tg account show [options]
OptionWhat it does
--show-phoneprint 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]
OptionWhat 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 list

tg account sessions end

log out every other device, your phone included; this one stays

Changes something in Telegram.

tg account sessions end [options]
OptionWhat it does
--othersevery 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 list

tg models audio download

download a speech model once, checked against the sha256 this version expects

tg models audio download <model>
ArgumentRequirementWhat it is
modelrequireda model id from models audio list.

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 list

tg models text download

download an embedding model once, checked against the sha256 this version expects

tg models text download <model> [options]
ArgumentRequirementWhat it is
modelrequireda model id from models text list.
OptionWhat it does
--accept-termsaccept 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>
ArgumentRequirementWhat it is
providerrequiredopenai, 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>
ArgumentRequirementWhat it is
providerrequiredopenai, 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]
OptionWhat it does
--eventsalso 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 serve

tg 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 start

tg server stop

stop this profile's serve — through the unit if it runs under one

tg server stop

tg server restart

stop it and start it again

tg server restart

tg server status

whether serve runs for this profile, since when, who started it, and the unit if there is one

tg server status

tg server logs

serve's latest log lines — from the journal under systemd, else its log file

tg server logs [options]
OptionWhat 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 install

tg server uninstall

remove this profile's unit; stop it first

tg server uninstall

tg 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]
ArgumentRequirementWhat it is
chatoptionala 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>
ArgumentRequirementWhat it is
chatrequireda 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]
ArgumentRequirementWhat it is
chatrequireda chat: its title or part of it, its id, @username, or me for Saved Messages.
OptionWhat 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-upprepare local search after repair; overrides searchCatchUp.
--no-catch-upskip 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.
--backgroundrepair 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]
OptionWhat 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]
ArgumentRequirementWhat it is
joboptionalthe job id messages sync --background printed.

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>
ArgumentRequirementWhat it is
jobrequiredthe 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]
ArgumentRequirementWhat it is
joboptionalthe job id.
OptionWhat it does
--failedevery 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 clear

tg 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]
ArgumentRequirementWhat it is
chatsoptionala chat: its title or part of it, its id, @username, or me for Saved Messages; several with --to.
OptionWhat 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.
--allwith --to: every stored chat of this account.
--encryptcompress 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]
OptionWhat it does
--leftthe chats this account has left — the only thing this clears.
--allow-dangerousyes, 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 info

tg store check

whether the store is healthy — integrity, search indexes, disk, and which chats are behind

tg store check

tg 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 migrate

tg 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 reindex

tg store backup

copy the store into a new file, while it is in use; never overwrites a file

tg store backup <file> [options]
ArgumentRequirementWhat it is
filerequiredthe new file.
OptionWhat it does
--encryptcompress 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>
ArgumentRequirementWhat it is
filerequireda 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]
ArgumentRequirementWhat it is
filerequireda file store backup --encrypt or store export --encrypt wrote.
OptionWhat 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]
OptionWhat it does
--dry-runsay 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]
OptionWhat it does
--no-backupdelete 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>
ArgumentRequirementWhat it is
namerequiredthe copy's name, as store repair printed it.

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 clear

tg runs

recorded runs — what this tool did, and when

tg runs list

recorded runs, newest first

tg runs list [options]
OptionWhat 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>
ArgumentRequirementWhat it is
run-idrequiredan id from tg runs list.

search recorded diagnostic metadata and events; no message contents

tg runs search [query] [options]
ArgumentRequirementWhat it is
queryoptionalcase-insensitive literal diagnostic text.
OptionWhat 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>
ArgumentRequirementWhat it is
run-idrequiredan id from tg runs list.

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]
OptionWhat it does
--dry-runshow 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]
OptionWhat it does
--botthe 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]
ArgumentRequirementWhat it is
settingrequiredone 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..
valuerequireda number, true or false, or for allow a list like send,reaction; for a group tg:work,max:Alice,email:me@x.
OptionWhat it does
--defaultschange what every profile gets, rather than this profile.
--personalonly for personal accounts — the personal section of the file.
--botonly 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]
ArgumentRequirementWhat it is
settingrequiredone 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..
OptionWhat it does
--defaultschange what every profile gets, rather than this profile.
--personalonly for personal accounts — the personal section of the file.
--botonly for bots — the bot section of the file.

tg doctor

the state this installation is in, without connecting unless --online

tg doctor [options]
OptionWhat it does
--onlinealso 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]
OptionWhat 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>
ArgumentRequirementWhat it is
pathrequiredone command path, for example: stats messages show.

tg complete

shell completion: tg complete zsh prints the script to source

tg complete [words]
ArgumentRequirementWhat it is
wordsoptional

tg upgrade

upgrade tg with the package manager that installed it; --check only looks

tg upgrade [options]
OptionWhat it does
--checksay 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]
OptionWhat it does
--permission <key=level>override a permission for this server only; repeat for more keys.
--confirm-sendno longer used — writes show no form; the profile's permissions decide.
--allow-dangerousno longer used — writes show no form; the profile's permissions decide.
--allow-sendno longer used — the profile's permissions decide; kept so an old setup still starts.
--allow-mark-readno longer used — the profile's permissions decide.
--allow-deleteno longer used — the profile's permissions decide.
--httpserve 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.
--revokeforget 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]
OptionWhat it does
--permission <key=level>override a permission for this server only; repeat for more keys.
--confirm-sendno longer used — writes show no form; the profile's permissions decide.
--allow-dangerousno longer used — writes show no form; the profile's permissions decide.
--allow-sendno longer used — the profile's permissions decide; kept so an old setup still starts.
--allow-mark-readno longer used — the profile's permissions decide.
--allow-deleteno 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]
ArgumentRequirementWhat it is
clientrequiredcodex or claude-code.
OptionWhat it does
--allow-writesacknowledge that this profile offers writing tools.
--permission <key=level>override a permission for this server only; repeat for more keys.
--confirm-sendno longer used — writes show no form; the profile's permissions decide.
--allow-dangerousno longer used — writes show no form; the profile's permissions decide.
--allow-sendno longer used — the profile's permissions decide; kept so an old setup still starts.
--allow-mark-readno longer used — the profile's permissions decide.
--allow-deleteno longer used — the profile's permissions decide.

tg mcp doctor

check this profile's local MCP handshake and tool list

tg mcp doctor [options]
OptionWhat it does
--permission <key=level>override a permission for this server only; repeat for more keys.
--confirm-sendno longer used — writes show no form; the profile's permissions decide.
--allow-dangerousno longer used — writes show no form; the profile's permissions decide.
--allow-sendno longer used — the profile's permissions decide; kept so an old setup still starts.
--allow-mark-readno longer used — the profile's permissions decide.
--allow-deleteno 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]
ArgumentRequirementWhat it is
nameoptionalone 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]
OptionWhat 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.

CodeWhen
0it worked
2validation_error
3configuration_error
4authentication_error
5permission_error
6not_found
7confirmation_required
8rate_limited
9timeout
10network_error
11provider_error
12provider_unavailable
13invalid_response
14outcome_unknown
130cancelled
1anything 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.