configuration

Configuration

Use this page when you type the same option again and again, or when you want tg to behave differently for one account. By the end you will know where the settings file is, what the common settings do, how to change one, and how to check which value is in force. You do not need a settings file to start: without one, every setting has a built-in value.

A few words this page uses:

• Settings file (config.json): a text file where tg keeps your saved choices.
• Profile: a named set of settings for one Telegram account or one bot, such as work. You put its name before the command: tg work chats list. See profiles and bots.
• Option (or flag): a word added to one command, such as --limit 5. It changes only that run.
• Environment variable: a named value that your terminal or your agent's process gives to tg, such as TG_PROFILE=work.
• Default: the value tg uses when nothing else sets one.

What you can set

These are the settings most people change. Each one has an exact entry, with its type and every way to override it, in the settings reference.

Setting	What it does	Built-in value
limit	how many rows a list shows when you do not add --limit	20
sends_per_hour	the most messages this profile may send in one hour; stops a send loop	30; a bot has no limit until one is set in the bot section
requests_per_minute	how fast tg asks Telegram for things after a short burst; 0 turns the pace off (limits and waits)	60
permissions	what this profile may do: read only, ask first, or go ahead (permissions)	everything allowed, except: deleting and a few other changes that cannot be undone ask first; reply rules may not send
record	keep a record of every run, to look at later (diagnostics)	false
keep_runs_for_days	how many days run records are kept	30
color	colour in tables	decided by your terminal
sender_colors	a different colour for each sender in a message list	false
timeout_ms	how long one request to Telegram may wait, in milliseconds. To limit a whole command, use --timeout instead	the connection's own wait
catch_up_marks_read	inbox and review mark the chats they show as read. The other person sees it	false
proxy	a proxy server to reach Telegram through, where it is blocked (proxy setup)	none
transcribe_with	who turns voice messages into text: auto, messenger or local	auto
update_check	once a day, say when a newer tg exists	true
default_profile	which profile a command uses when you do not name one	none: a command that uses an account stops and lists the profiles

The file never holds a secret. It has no place for your session, the app hash, a phone number or a proxy password. The session is a file of its own, and the app hash and a proxy password go to your system's keyring, or, where there is none, to a file only you can read (where the login lives).

An example settings file

The first command that reads settings creates a starter file. It looks like this, with one profile added:

{
  "defaults": { "limit": 20, "keep_runs_for_days": 30, "sends_per_hour": 30, "update_check": true, "skill_hint": true },
  "profiles": {
    "work": { "limit": 50 }
  }
}

• defaults applies to every profile.
• profiles.work applies only to the profile work and wins over defaults.

So tg work chats list shows 50 rows, and tg personal chats list shows 20. Add --limit 5 to get five for one command. Remove the profile's limit and the value from defaults applies again.

A full example with every section

{
  "default_profile": "personal",
  "defaults": {
    "limit": 20,
    "keep_runs_for_days": 14,
    "sends_per_hour": 30,
    "requests_per_minute": 60,
    "update_check": true,
    "skill_hint": true
  },
  "profiles": {
    "personal": {
      "limit": 50,
      "color": true,
      "sender_colors": true,
      "record": true
    },
    "work": {
      "permissions": { "messages": "readonly", "messages.send": "allow" },
      "sends_per_hour": 10,
      "proxy": "socks5://proxy.example:1080",
      "transcribe_with": "local"
    }
  },
  "personal": {
    "defaults": { "catch_up_marks_read": false, "search_catch_up": true }
  },
  "bot": {
    "defaults": { "permissions": { "bot": "readonly", "bot.messages.send": "allow" } },
    "profiles": {
      "shop": { "sends_per_hour": 200, "read_other_bots": false }
    }
  }
}

What each part does:

• default_profile: tg chats list with no profile name uses personal.
• defaults: every profile gets these values unless it sets its own. update_check and skill_hint are allowed only here, because there is one copy of tg for all profiles.
• profiles.personal: more rows, colours, and a record of every run, only for personal.
• profiles.work: reading messages is allowed, sending is allowed, every other change to messages is refused. At most 10 sends an hour. Telegram is reached through a SOCKS5 proxy. Voice messages are turned into text on this computer.
• personal.defaults: applies only to commands for personal accounts, never to tg … bot. Here, messages sync also prepares fetched chats for search.
• bot.defaults: applies only to bot commands (tg shop bot …). Bots may read and send, and nothing else.
• bot.profiles.shop: the bot shop may send 200 messages an hour and may not read what other bots on this computer saved. read_other_bots is allowed only in the bot section.

Where the file is

System	Path
Linux and macOS	~/.config/tg-cli/config.json
Windows	%APPDATA%\tg-cli\Config\config.json

tg config show prints the path this computer actually uses, and every setting with its value. In PowerShell, type tg.cmd instead of tg. An existing file is never replaced by the starter file.

Three ways to set a value

• In the file: the value stays for later commands. tg config set limit 50 saves it.
• With an environment variable: the value holds for one terminal or one agent process. For example, TG_PROFILE chooses a profile and TG_TIMEOUT limits how long a command may run. Only some settings have a variable.
• With an option: --limit 5 changes only this one command.

Which value wins?

An option wins over an environment variable. Then comes the profile's own value in the file, then defaults in the file, then the built-in value. A setting takes part only in the ways it supports; the settings reference lists them for each setting.

Change a value

You can edit the file in any text editor, or let tg do it. config set checks the value before it writes, so it never saves a file that a later command refuses.

tg config set limit 50                 # the profile you use now
tg work config set limit 50            # the profile "work"
tg config set sends_per_hour 10 --defaults   # every profile
tg config unset limit                  # back to the default
tg config show                         # check what is in force, and where each value came from

A misspelled setting in the file is an error, not a silent default: every command stops and names the wrong key (typos in the file).

Profiles and bots

A profile keeps settings for one account or one bot. Put its name before the command, such as tg work config show. Add bot after the name to work as a bot rather than as your personal account. Profiles and bots explains how to create and switch them.

Next

• Permissions: choose what a profile, and the agent that uses it, may do.
• Settings reference: every setting, its type, where it may appear, and every environment variable.