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 telegram | Purpose |
|---|---|
auth login [--qr] | Sign in interactively |
auth status | Report the session, the authorization state, and the account the peer cache belongs to |
auth logout | Revoke the session and remove its local file |
fetch dialogs | List dialogs with account status and populate the peer cache |
fetch topics --dialog UID | List a forum’s topics |
fetch peer REF… | Describe channels, groups, users, and invite links, one record per ref |
fetch messages --dialog UID | Walk conversation or topic history |
fetch message LINK… | Fetch exact messages; also accepts --dialog UID --id 11,46 |
fetch media --dialog UID --dir PATH | Download files and emit a JSONL manifest |
debug uid VALUE | Parse 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 skill | Purpose |
|---|---|
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 |
info | Print 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
| Flag | Default | Meaning |
|---|---|---|
--limit | 0 | Maximum emitted records; 0 means all |
--page-size | 100 | History/dialog/topic page size; values outside 1–100 reset to 100 |
-o, --output | - | stdout, or a file opened in append mode |
--format | jsonl | Only 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
| Flag | Meaning |
|---|---|
--env-file PATH | Use a particular configuration file; --env-file="" disables file loading |
--session PATH | Use a particular Telegram session |
--peer-cache PATH | Use a particular peer cache |
--timeout 5m | Total Telegram operation budget; default 0 has no deadline |
-v | Debug logging; -vvv also enables gotd internals |
-q | Show 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:
- The path passed to
--env-file. - The path in
INDEXIT_ENV_FILE. .envin the current directory.$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 statusThe 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
| Address | Target |
|---|---|
@example_channel, https://t.me/example_channel | Public 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/46 | Public dialog with message anchor |
https://t.me/example_forum/42/46 | Public 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_channel | Public 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:
| Field | Meaning |
|---|---|
is_member | Whether the account currently belongs to the chat; false for chats it left and for migrated or deactivated basic groups |
is_admin | Whether the account is the owner or has admin rights |
is_creator | Whether 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>' | fxA 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.
| Field | Meaning |
|---|---|
ref | The ref as passed |
uid, peer_id | channel:<id>, chat:<id>, or user:<id>, and the numeric ID |
peer_type | channel, supergroup (gigagroups included), chat, user, or bot |
title, username, usernames | Name, main username, other active usernames |
about, participants_count | Description or bio, and member count |
is_member, is_admin, is_creator | Current account’s membership, administration (owners included), and ownership; see account status |
linked_chat_uid, linked_chat | The discussion group of a channel, or the channel of a discussion group, with uid, title, username |
verified, scam, fake, restricted | Telegram flags; restricted carries the restriction text |
first_name, last_name, phone, lang_code | A 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, deleted | User flags: Telegram Premium, a Telegram support account, a deleted account |
personal_channel_uid, personal_channel | The channel a user shows on the profile, with uid, title, username, shaped like linked_chat |
birthday | YYYY-MM-DD, or --MM-DD when the profile hides the year |
business | A 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) |
bot | A 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_stars | A 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 |
date | Telegram’s date of the channel or group: when the account joined it, or when it was created |
invite | For invite links: hash, member, and optional peek, expires, request_needed |
error | code 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:
| Code | Cause |
|---|---|
bad_ref | The ref is not a Telegram address |
not_found | The username is free or invalid |
cold_peer | A 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_member | The invite leads to a chat the account is not in |
invite_expired | The invite link is expired or revoked |
rpc | Any 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.