Profiles#

tgs supports multiple Telegram accounts through profiles — similar to how AWS CLI handles credentials. Each profile has its own independent session stored in a separate database file.

How Profile Resolution Works#

When you run any tgs command, the active profile is determined by this priority chain (highest wins):

  1. --profile flag passed to the command
  2. TGS_PROFILE environment variable
  3. .tgs.yaml file in the current directory or any parent directory
  4. "default" (fallback)

Per-Directory Profiles#

You can bind a profile to a directory by creating a .tgs.yaml file. Use tgs profile switch to do this automatically:

cd ~/projects/work-project
tgs profile switch work
profile: work

tgs walks up the directory tree to find .tgs.yaml, so it applies in all subdirectories too. This is the recommended way to use different accounts per project.

Managing Profiles#

List profiles#

tgs profile list
* default (@myuser)
  work (@workuser)

The * marks the currently active profile. JSON output is the default and includes an active field.

Switch profile for current directory#

tgs profile switch work

This creates or overwrites .tgs.yaml in the current directory.

Delete a profile#

tgs profile delete old-account
tgs profile switch default
tgs profile delete work

Deletes the profile directory and its session database. You cannot delete the currently active profile — switch to another profile first.

Check current profile and account#

tgs whoami
tgs whoami --output text
Profile: work
User:    John Doe (id: 123456789)
Handle:  @johndoe
Phone:   +1234567890

whoami reads from local storage — it does not connect to Telegram.

Environment Variable#

Set TGS_PROFILE to override the profile for a single command or for the whole shell session:

# One-off override
TGS_PROFILE=work tgs whoami

# Override for the shell session
export TGS_PROFILE=work

The --profile flag always takes precedence over TGS_PROFILE.

Practical Examples#

tgs --profile work search "design review"
mkdir ~/projects/client-x && cd ~/projects/client-x
tgs login --type code --profile client-x
tgs profile switch client-x
tgs whoami --output text

Full Reference#

Backward Guide Search Forward