Inicio de sesión y perfiles

Antes de empezar, abre Telegram en tu teléfono y comprueba que has iniciado sesión en la cuenta que quieres conectar. Tenlo a mano para leer códigos o escanear el QR.

La conexión tiene dos pasos:

1. Obtener credenciales de la aplicación Telegram: api_id (identificador numérico) y api_hash (clave secreta) de my.telegram.org. Permiten a tg identificar el programa ante Telegram. Normalmente solo se hace en el primer acceso de cada perfil.
2. Confirmar el acceso a tu cuenta mediante QR o código. tg guarda una sesión: datos de autorización para ejecutar comandos sin volver a iniciar sesión.

tg setup guía el primer uso: prepara ambas partes, comprueba cinco chats y ofrece una skill para el agente. Reserva unos cinco minutos; descargar historial es un paso aparte. Ejecútalo en una terminal. Usa tg setup --app browser para registrar la aplicación manualmente o --method phone para acceder por teléfono. tg session start sigue siendo el comando para solo iniciar sesión, incluido retomar un acceso interrumpido. Setup comprueba una sesión existente y no inicia otra en silencio si Telegram la rechaza.

La aplicación de my.telegram.orgCopy Anchor Link

my.telegram.org/apps es el sitio oficial de Telegram para registrar credenciales de conexión. Usa el número de tu cuenta Telegram.

Obtener credenciales manualmente en el navegador — método predeterminado:

tg session start --app browser

1. El comando abre my.telegram.org/apps. Si el navegador no se abre, entra mediante el enlace.
2. Introduce el número en formato internacional, por ejemplo +34600111222. El código del sitio llega por mensaje a Telegram en un dispositivo donde ya has iniciado sesión.
3. Si no hay una aplicación, rellena API development tools: título, nombre corto y plataforma Desktop. Omite este paso si ya aparece una aplicación.
4. Copia App api_id y App api_hash en la terminal cuando se soliciten. El hash no se muestra al escribirlo; es normal.
5. La terminal muestra un QR para acceder a tu cuenta. Sigue las instrucciones de escaneo de abajo.

Rellenar el sitio automáticamente:

tg session start --app auto

El comando pide el número y el código que Telegram envía para my.telegram.org, obtiene la aplicación existente o la registra y muestra el QR. Si falla, ejecuta el comando completo tg session start --app browser y sigue los pasos anteriores.

Las credenciales se guardan solo tras un acceso correcto a la cuenta. El código de my.telegram.org y el código de acceso a la cuenta son confirmaciones distintas: usa el mensaje correspondiente a la petición actual de la terminal.

Iniciar sesiónCopy Anchor Link

Entrar por QR:

tg session start

1. Si aún no hay credenciales guardadas, responde primero a las preguntas sobre la aplicación indicadas arriba.
2. Deja abierta la terminal con el QR en el ordenador.
3. Abre Telegram en tu teléfono y selecciona la cuenta que quieres conectar.
4. Entra en Ajustes → Dispositivos → Vincular dispositivo de escritorio. El último nombre puede variar según la versión. Se abrirá el escáner de Telegram.
5. Apunta al QR de la terminal y confirma el acceso si se solicita. Usa el escáner de Telegram, no la aplicación de cámara habitual.
6. Si tienes verificación en dos pasos (2FA), introduce su contraseña adicional en la terminal. Los caracteres no se muestran.
7. Espera Logged in as …. Si el QR caduca, escanea el código actualizado de la terminal.

Entrar por número de teléfono:

tg session start phone

1. La primera vez, obtén las credenciales de la aplicación como se explica arriba.
2. Introduce el número en formato internacional, por ejemplo +34600111222.
3. Lee el aviso de la terminal sobre la entrega del código. Normalmente llega al chat oficial Telegram en un dispositivo conectado; Telegram puede elegir SMS. Telegram decide el método. El SMS puede no estar disponible para un CLI de terceros: accede primero con la aplicación oficial del teléfono y usa un código de Telegram o QR. Cómo Telegram entrega códigos.
4. Introduce el código reciente en la petición login code.
5. Si tienes 2FA, introduce después la contraseña que configuraste anteriormente; no es otro código temporal.
6. Espera Logged in as …. Si se rechaza el código, sigue las indicaciones; no uses el código de my.telegram.org como código de acceso a la cuenta.

El CLI aparece como otro dispositivo en Ajustes → Dispositivos. El ejemplo siguiente muestra la cuenta y la ruta de la sesión; la ruta depende del sistema. Rutas de Windows, macOS y Linux.

Logged in as <your name> (@<username>, id <id>) — profile default.
Session:  ~/.local/share/tg-cli/sessions/default.session
App keys: in the keyring
Next:     tg chats list · tg server install to keep the archive current

Cuando un agente inicia la sesiónCopy Anchor Link

Un agente no tiene una terminal donde dibujar el QR. --qr-file lo guarda como PNG para que el agente pueda mostrártelo:

tg session start --qr-file login.png

El archivo se sustituye cuando Telegram renueva el código y se elimina al finalizar el inicio de sesión, tenga éxito o no. Sin terminal, esto solo funciona si el perfil ya tiene su aplicación y la cuenta no tiene contraseña 2FA: cualquier otro dato debe introducirse manualmente.

Comprobar la cuenta y cerrar sesiónCopy Anchor Link

tg account show              # who this profile is logged in as
tg account sessions list     # every device and app logged in to the account; ends nothing
tg session end               # log out on Telegram's side, and delete the session file here

tg session end también cierra la sesión en Telegram: el dispositivo desaparece de la lista de la aplicación. No elimina el identificador ni el hash de la aplicación del almacén de claves y deja intacto el archivo local.

Cuánto dura una sesiónCopy Anchor Link

tg no establece una duración fija como «30 días desde el acceso». Cerrar la terminal o reiniciar el ordenador no finaliza la sesión guardada. Funciona mientras Telegram acepta la autorización.

Finaliza al ejecutar tg session end, eliminar el dispositivo en Telegram o revocar Telegram la autorización. Las sesiones sin uso dependen de Ajustes → Dispositivos → Finalizar sesiones antiguas automáticamente. El periodo cuenta desde el último uso de esa sesión, no desde el primer acceso.

El cliente oficial Telegram Desktop ofrece actualmente 1 semana, 1 mes, 3 meses, 6 meses y 1 año (365 días) sin actividad. Un año es la opción máxima de ese menú, no la duración total máxima de una sesión que se utiliza. Comprueba el valor en tu aplicación; las opciones pueden cambiar. Ajuste de la API y código del cliente oficial.

Si un comando responde “not logged in, or the session was ended” con código 4, vuelve a entrar:

tg session start

Para el perfil laboral, usa tg work session start. Solución de problemas.

PerfilesCopy Anchor Link

Un perfil es una conexión con nombre a una cuenta Telegram en el CLI. Normalmente usas uno por número: default para la cuenta personal y work para la cuenta laboral. Cada conexión tiene su sesión, credenciales de aplicación, ajustes, destinatarios permitidos y ejecuciones.

work es una etiqueta que eliges, no un número. Conecta la cuenta laboral con:

tg work session start --app browser

Usa el número laboral para registrar credenciales; para el QR, cambia Telegram del teléfono a la cuenta laboral. Comprueba después qué cuenta corresponde a la etiqueta:

tg work account show

Puedes conectar la misma cuenta en varios perfiles; un perfil no crea una cuenta Telegram. Su nombre es la primera palabra después de tg, antes del comando:

tg chats list              # profile "default"
tg work chats list         # profile "work"
export TG_PROFILE=work     # the same for the whole shell session

La primera palabra es el perfil si no es un comando. Por eso un perfil no puede llamarse chats, messages ni usar otra palabra de comando; tg session start rechaza esos nombres. Los nombres admiten letras, cifras, puntos, guiones y guiones bajos, y deben empezar por una letra o cifra.

El orden de prioridad, de mayor a menor, es: primera palabra, TG_PROFILE, defaultProfile en la configuración y, por último, default.

Si una palabra no es un comando y no va seguida de ningún comando, se muestra este error:

"nonsense" is not a command, so it was read as a profile name — and no command followed it.

TG_PROFILE_LOCK limita un proceso a un perfil. Defínelo en el entorno del agente: cualquier primera palabra o TG_PROFILE que indique otro perfil se rechazará (código de salida 5). Sin él, un agente podría elegir un perfil con menos restricciones.

Dónde se guarda cada parteCopy Anchor Link

Consulta las rutas en instalación.

En equipos sin almacén de claves (habitual en contenedores), la aplicación se guarda en credentials.json, junto a la configuración. tg lo avisa una vez por stderr.

⚠ TG_CONFIG_DIR, TG_STATE_DIR y TG_CACHE_DIR también cambian la entrada del almacén de claves. Si alguna está definida, el nombre del servicio incluye el directorio de configuración. Una sesión creada sin ellas no es visible al definirlas, y viceversa. Úsalas siempre o nunca.

⚠ En Linux se accede al almacén de claves mediante XDG_RUNTIME_DIR. cron, ssh y algunos clientes MCP inician tg sin ella, por lo que todos los comandos indican que no se encuentran las credenciales "although it has logged in on this machine". No vuelvas a iniciar sesión: añadirías otro dispositivo sin resolver el entorno. Define XDG_RUNTIME_DIR (solución de problemas).

Siguientes pasosCopy Anchor Link

• Primeros pasos: los primeros comandos.
• Configuración: ajustes y orden de prioridad.
• Seguridad: qué se guarda en disco y qué nunca se guarda.