Authentication #

tg authenticates against your atproto PDS. Log in interactively with OAuth:

tg auth login alice.example.com

For headless use, pass an atproto app password as the second argument:

tg auth login alice.example.com xxxx-xxxx-xxxx-xxxx

To avoid exposing the app password in shell history, pass it on standard input:

printf '%s\n' "$ATPROTO_APP_PASSWORD" | tg auth login alice.example.com --password-stdin

Multiple accounts #

Multiple accounts can be stored at once. Logging in adds or replaces that account and selects it as the default.

• tg auth list — list stored accounts
• tg auth switch <handle-or-did> — select the default account
• tg auth status — show the active account
• tg auth logout — remove the selected account (--all removes every account)

Use --account <handle-or-did> (or TG_ACCOUNT) for a one-command override of the default account.

Token storage #

tg stores OAuth and app-password sessions in the system keyring: macOS Keychain or the Secret Service on Linux (GNOME Keyring / KWallet). The keyring unlocks with your login session, so no separate passphrase is needed.

The keyring is accessed on first use (not at startup), so authentication only fails once you run a command that needs a session. On Linux this requires a Secret Service provider to be running; on a headless system without a D-Bus session bus (e.g. a server or container), install and start gnome-keyring-daemon or kwalletd, or set DBUS_SESSION_BUS_ADDRESS.

Insecure file storage (--insecure) #

For an app-password login without a keyring, use --insecure:

tg auth login alice.example.com xxxx-xxxx-xxxx-xxxx --insecure

This stores one account in plaintext at $XDG_DATA_HOME/tg/credentials.json (default ~/.local/share/tg/credentials.json); logging in again overwrites it. The directory and file are created with 0700 and 0600 permissions.

Use the keyring when available. --insecure requires an app password; it does not support OAuth.

See the command reference for the full tg auth subcommand list.