Skip to Content
DocumentationCLI & configuration

The essentials, in one place

Use indexit <command> --help for help at any level. All examples describe the current v0.4.1 feature set.

Commands

Command prefix: indexit telegramPurpose
auth login [--qr]Sign in interactively
auth statusReport the session, the authorization state, and the account the peer cache belongs to
auth logoutRevoke the session and remove its local file
fetch dialogsList dialogs with account status and populate the peer cache
fetch topics --dialog UIDList a forum’s topics
fetch peer REF…Describe channels, groups, users, and invite links, one record per ref
fetch messages --dialog UIDWalk conversation or topic history
fetch message LINK…Fetch exact messages; also accepts --dialog UID --id 11,46
fetch media --dialog UID --dir PATHDownload files and emit a JSONL manifest
debug uid VALUEParse an address without connecting to Telegram

indexit version shows the build version. indexit completion bash, zsh, fish, or powershell generates shell completion scripts.

Command prefix: indexit skillPurpose
install --agent claude-code,codex [--project] [--replace]Install the agent skill that ships with this binary
status [--agent NAME] [--exact]Check every installed copy against this binary
show [--file PATH]Print the skill or one of its files
infoPrint the skill’s version, compatible range, and digest
export -o DIR [--replace]Write the skill into any directory

The skill commands work offline and do not read .env. info and status accept --json.

Fetch flags

FlagDefaultMeaning
--limit0Maximum emitted records; 0 means all
--page-size100History/dialog/topic page size; values outside 1–100 reset to 100
-o, --output-stdout, or a file opened in append mode
--formatjsonlOnly JSONL is supported

For fetch message, --page-size has no effect. Requests contain at most 100 IDs. fetch peer ignores both --limit and --page-size.

For messages and media, use --from / --to for RFC3339 dates, and --min-id / --max-id for exclusive ID bounds. Media adds --media photo,video and --overwrite. See export conversations and save media for behavior and examples.

Runtime flags

FlagMeaning
--env-file PATHUse a particular configuration file; --env-file="" disables file loading
--session PATHUse a particular Telegram session
--peer-cache PATHUse a particular peer cache
--timeout 5mTotal Telegram operation budget; default 0 has no deadline
-vDebug logging; -vvv also enables gotd internals
-qShow only errors on stderr; does not change stdout
--heartbeat 10s“Still waiting” interval for network calls; 0 disables it

-q and -v are mutually exclusive. For logging, use these flags; INDEXIT_LOG_LEVEL is not wired into the current implementation.

Configuration lookup

indexit loads the first selected configuration file:

  1. The path passed to --env-file.
  2. The path in INDEXIT_ENV_FILE.
  3. .env in the current directory.
  4. $XDG_CONFIG_HOME/indexit/.env, or ~/.config/indexit/.env.

An explicitly selected missing file is an error. If neither an explicit file nor an auto-discovered file exists, the process environment is used.

Values in the loaded file override matching environment variables. Other environment variables remain available. To use only the process environment:

indexit --env-file="" telegram auth status

The file supports KEY=value, single or double quotes, and an optional export prefix. It does not expand shell variables or execute commands.

Required credentials are TELEGRAM_API_ID and TELEGRAM_API_HASH. Proxy settings are listed in connect through a proxy. No GitHub credentials are needed for the implemented Telegram commands.

Accepted addresses

AddressTarget
@example_channel, https://t.me/example_channelPublic username
user:@example_user, user:<id>User by username or cached numeric ID
chat:<id>, -<id>Basic group
channel:<id>, -100<id>Cached channel or supergroup
channel:<id>:<topic>, -100<id>:<topic>Forum topic
https://t.me/example_channel/46Public dialog with message anchor
https://t.me/example_forum/42/46Public topic with message anchor
https://t.me/c/<id>/<message>Private dialog with message anchor
https://t.me/c/<id>/<topic>/<message>Private topic with message anchor
https://t.me/s/example_channelPublic channel preview, same as the username
https://t.me/+<hash>, https://t.me/joinchat/<hash>Invite link; only fetch peer accepts it

Four-letter usernames are accepted. Bare positive numbers are ambiguous and rejected. Numeric user/channel IDs and t.me/c/ links require the peer cache. Run fetch dialogs first. A cache entry does not grant access your account lacks, and a cache written for another account is never used: see where the files live.

Account status

fetch dialogs and fetch peer include these fields for the signed-in account in channels, supergroups (gigagroups included), and basic groups:

FieldMeaning
is_memberWhether the account currently belongs to the chat; false for chats it left and for migrated or deactivated basic groups
is_adminWhether the account is the owner or has admin rights
is_creatorWhether the account is the owner

Known values are emitted as true or false. Unknown or inapplicable values are omitted: reduced (min) channels, channel direct-message inboxes (monoforums), inaccessible or missing entities, invite-only previews, and users/bots have no account status fields. invite.member separately reports membership learned from an invite link. Older binaries may omit the new fields as well.

Telegram can retain owner/admin flags on migrated basic groups or channels the owner left. To find owned chats the account currently belongs to, require both is_member == true and is_creator == true.

A peer record with error can retain account status from an entity already returned by an invite check when the subsequent full fetch fails. Check error before relying on the rest of the card.

fetch dialogs reads this information from its existing responses, without a request per peer. Use explicit comparisons such as is_member == true and is_admin == false, and report unknown status separately. Titles and member counts do not establish ownership. These fields describe only the signed-in account, so they cannot identify another person’s chats where that account is an ordinary member.

Filter your dialogs by account status →

Peer cards

For practical workflows, see describe channels and groups.

fetch peer turns each ref into one peer record, in the order of the refs:

indexit -q telegram fetch peer @example_channel 'https://t.me/+<hash>' | fx

A ref is any address above, a bare https://t.me/c/<id>, or an invite link; links work without https://. Channels and supergroups are read with channels.getFullChannel, basic groups with messages.getFullChat, users and bots with users.getFullUser. A user or a bot is a card like any other, not an error: tell people from chats by peer_type. A cached user:<id> ref reports bot once the full response arrives; if that request fails, its record falls back to peer_type: "user".

Refs are processed in order, so a username or an invite placed before the numeric ID of the same channel warms the peer cache for it.

FieldMeaning
refThe ref as passed
uid, peer_idchannel:<id>, chat:<id>, or user:<id>, and the numeric ID
peer_typechannel, supergroup (gigagroups included), chat, user, or bot
title, username, usernamesName, main username, other active usernames
about, participants_countDescription or bio, and member count
is_member, is_admin, is_creatorCurrent account’s membership, administration (owners included), and ownership; see account status
linked_chat_uid, linked_chatThe discussion group of a channel, or the channel of a discussion group, with uid, title, username
verified, scam, fake, restrictedTelegram flags; restricted carries the restriction text
first_name, last_name, phone, lang_codeA user’s names, the phone number, and the user’s language code, each as Telegram returns it; lang_code comes mostly for your own account
premium, support, deletedUser flags: Telegram Premium, a Telegram support account, a deleted account
personal_channel_uid, personal_channelThe channel a user shows on the profile, with uid, title, username, shaped like linked_chat
birthdayYYYY-MM-DD, or --MM-DD when the profile hides the year
businessA business account’s location (address, latitude, longitude), work_hours (timezone_id, weekly_open spans of start_minute, end_minute counted from Monday 00:00), and intro (title, description)
botA bot’s description, commands (command, description), privacy_policy_url, active_users (absent when Telegram doesn’t report it), inline_placeholder, and the explicit can_join_groups, can_read_all_group_messages, has_main_app
stars_rating, send_paid_messages_starsA user’s Stars rating (level, stars) and the Stars price of a message to them; 0 means paid messages are on but your account is exempt, an absent field means messages are free
dateTelegram’s date of the channel or group: when the account joined it, or when it was created
inviteFor invite links: hash, member, and optional peek, expires, request_needed
errorcode and message when the ref could not be described in full

What privacy settings hide is simply absent from a user card, with no error. Profile photos, stories, gifts, decoration such as emoji status or colours, and what a profile means only to your account, such as blocking or notification settings, are not part of the card.

indexit never joins a chat. An invite to a chat the account is in, or may peek into, yields the full card. An invite to any other chat yields only Telegram’s preview — title, description, member count, type — without an ID, and the error invite_not_member.

A failed ref does not stop the run; its record carries error.code:

CodeCause
bad_refThe ref is not a Telegram address
not_foundThe username is free or invalid
cold_peerA numeric ID is not in the peer cache, or names a user known only from a passing mention such as a message in a large group; such a user keeps the identity it left (uid, title, username), a never-seen ID has none. After you switch accounts, the cache starts empty. Run fetch dialogs or pass a username
invite_not_memberThe invite leads to a chat the account is not in
invite_expiredThe invite link is expired or revoked
rpcAny other Telegram error, such as a private channel or a stale cached user; the record keeps the identity already known

Exit status

0 means the command completed, including empty or partial results. 1 is a runtime failure. 2 covers flagged usage/configuration errors, such as invalid fetch UIDs, missing required flags, or malformed proxy settings.

fetch peer exits with 0 when at least one record has no error; when every ref fails, it exits with 1, or 2 if every ref was malformed. For specific-message exports, inspect stderr for skipped IDs. For media, inspect records with error: individual download failures can coexist with exit code 0.