Configuración y mantenimiento

Acceso, perfiles, configuración, servidor en segundo plano, almacén local, diagnóstico, conexión del agente y actualizaciones.

Esta referencia reúne comandos de configuración y mantenimiento. Consulta opciones de acceso, perfiles, configuración, servidor en segundo plano, almacén local, diagnóstico y conexión del agente.

Acceso, perfiles, configuración, servidor en segundo plano, almacén local, diagnóstico, conexión del agente y actualizaciones.

Opciones comunes a todos los comandos

OpciónQué hace
-V, --versionmuestra el número de versión.
-v, --verboseañade detalles: -v muestra identificadores, -vv todos los datos conocidos. Valor predeterminado: 0.
--jsonsalida para programas: un único valor JSON por stdout, nada más.
--agent-jsonJSON para agentes de IA: muestra los controles invisibles; --json normal conserva el texto.
--jsonlsalida para programas: un objeto JSON por línea, para flujos y jq.
--quietoculta los mensajes de diagnóstico, pero sigue mostrando fallos.
--traceregistros de la conexión por stderr; nunca el contenido de mensajes.
--debugante un fallo, su registro completo —causa y pila— en lugar de la línea breve.
--timeout <duration>detiene todo el comando después de este intervalo: 30s, 2m, 500ms.
--offlineresponde desde lo guardado sin conectarse; falla si no hay datos.
--no-inputno pedir entrada ni abrir un inicio de sesión interactivo; la entrada mediante una tubería sigue disponible.
--max-input-bytes <bytes>máximo de bytes de entrada almacenados en búfer (predeterminado: 16777216).
--max-output-bytes <bytes>máximo de bytes de salida para máquinas (predeterminado: 4194304; 0 desactiva el límite).
--fields <paths>campos de elementos o del objeto separados por comas: id,text; conservar la paginación y los identificadores de operaciones.
--briefmensajes y correo encontrados solo con referencia, título, hora, remitente y fragmento.
--fullmensajes y correo encontrados con su texto completo y todos los campos del proveedor.
--dry-runprevisualizar los argumentos analizados y los permisos antes de ejecutar la acción.
--yesomite la confirmación que el nivel ask exige antes de escribir.
--recordguarda esta ejecución: identificadores y tiempos, nunca contenido.
--no-recordno guarda la ejecución, independientemente de la configuración.

Comandos

tg session

inicia o cierra la sesión de Telegram de este perfil

tg session start

inicia sesión mediante QR (predeterminado) o teléfono, código y contraseña 2FA

tg session start [method] [options]
ArgumentoObligatoriedadQué es
methodopcionalmétodo de acceso. Valores: qr, phone. Predeterminado: qr.
OpciónQué hace
--app <how>solo la primera vez: cómo obtener la aplicación de my.telegram.org para el perfil. Valores: browser, auto. Predeterminado: browser.
--qr-file <png>guarda el QR en este PNG en lugar de dibujarlo, para que un agente pueda mostrártelo.
--smsacceso por teléfono: pedir el código por SMS; Telegram puede rechazarlo.

tg session end

cierra la sesión del perfil en Telegram y elimina su archivo local

Changes something in Telegram.

tg session end

tg setup

configura Telegram y conecta tu agente

Changes something in Telegram.

tg setup [options]
OpciónQué hace
--agent <agent>instala la skill para este agente; pregunta en una terminal, de lo contrario no instala ninguna. Valores: none, codex, cursor, claude, gemini, all.
--app <how>cómo obtener las credenciales de aplicación Telegram la primera vez. Valores: auto, browser. Por defecto: auto.
--method <method>cómo iniciar sesión si no existe una. Valores: qr, phone. Por defecto: qr.
--qr-file <png>guarda una imagen QR temporal para el acceso del agente; sin terminal requiere credenciales de aplicación guardadas.

tg account

la cuenta conectada

tg account list

todos los perfiles de este ordenador y sus cuentas; no consulta el servicio de mensajería

tg account list

tg account show

cuenta con la que inició sesión el perfil; solo muestra las cuatro últimas cifras del teléfono

tg account show [options]
OpciónQué hace
--show-phonemuestra el número completo.

tg account update

cambia nombre, descripción o foto visibles de tu perfil

Changes something in Telegram.

tg account update [options]
OpciónQué hace
--first-name <name>tu nombre.
--last-name <name>tus apellidos.
--description <text>información sobre ti.
--photo <file>nueva foto de perfil: un archivo de imagen.

tg account sessions

otras sesiones de la cuenta; no es tg session, que gestiona la sesión de esta herramienta

tg account sessions list

todos los dispositivos y aplicaciones con sesión en esta cuenta, sin cerrar ninguno

tg account sessions list

tg account sessions end

cierra todos los demás dispositivos, incluido el móvil; conserva este

Changes something in Telegram.

tg account sessions end [options]
OpciónQué hace
--otherstodas las sesiones salvo esta.

tg models

modelos que se ejecutan en este equipo

tg models audio

modelos para transcribir voz

tg models audio list

modelos de voz, más adecuados primero, cuáles están descargados y cuál es el predeterminado

tg models audio list

tg models audio download

descarga un modelo y verifica el sha256 esperado por esta versión

tg models audio download <model>
ArgumentoObligatoriedadQué es
modelobligatorioidentificador de modelo de models audio list.

tg models text

modelos vectoriales para buscar conversaciones por significado

tg models text list

modelos vectoriales, más adecuados primero, descargados y predeterminado

tg models text list

tg models text download

descarga un modelo vectorial y comprueba el sha256 esperado por la versión

tg models text download <model> [options]
ArgumentoObligatoriedadQué es
modelobligatorioidentificador de models text list.
OpciónQué hace
--accept-termsacepta las condiciones de licencia específicas del modelo.

tg models text key

claves API de los proveedores de vectores y de análisis

tg models text key set

guarda una clave introducida oculta o por stdin; nunca como argumento

tg models text key set <provider>
ArgumentoObligatoriedadQué es
providerobligatorioopenai, anthropic o el servidor de --base-url que requiere una clave.

tg models text key remove

elimina una clave guardada

tg models text key remove <provider>
ArgumentoObligatoriedadQué es
providerobligatorioopenai, anthropic o el nombre de host del servidor.

tg watch

imprime mensajes nuevos hasta Ctrl-C o --timeout; ambos finalizan normalmente

tg watch [options]
OpciónQué hace
--eventsincluye ediciones, eliminaciones y reacciones; cada línea indica su evento.

tg serve

mantiene actualizado el archivo local hasta detenerlo; lo ejecutan unidades systemd o launchd

tg serve

tg server

tg serve en segundo plano: iniciar, detener, reiniciar, estado y registros; install añade una unidad systemd o launchd

tg server start

inicia serve en segundo plano mediante la unidad si existe y responde cuando se conecta

tg server start

tg server stop

detiene serve de este perfil mediante su unidad, si la utiliza

tg server stop

tg server restart

lo detiene y vuelve a iniciarlo

tg server restart

tg server status

si serve está activo para el perfil, desde cuándo, quién lo inició y unidad si existe

tg server status

tg server logs

últimos registros de serve, desde systemd o su archivo de registros

tg server logs [options]
OpciónQué hace
-n, --lines <n>número de líneas. Predeterminado: 50.

tg server install

crea una unidad systemd o agente launchd para el perfil, sin iniciarlo

tg server install

tg server uninstall

elimina la unidad del perfil; detenla primero

tg server uninstall

tg store

archivo local de mensajes

tg store status

por chat: cantidad guardada, más antiguo y reciente, y tramos completos

tg store status [chat]
ArgumentoObligatoriedadQué es
chatopcionalchat por título completo o parcial, identificador, @username o me para Mensajes guardados.

tg store gaps

inspeccionar las lagunas internas de cobertura registradas y descargar explícitamente los datos que faltan

tg store gaps plan

plan de cobertura local; los identificadores de mensajes ausentes no implican por sí solos que falte historial

tg store gaps plan <chat>
ArgumentoObligatoriedadQué es
chatobligatoriochat por título completo o parcial, identificador, @username o me para Mensajes guardados.

tg store gaps repair

descargar datos de lagunas internas con límites y volver a comprobar la cobertura; nunca eliminar los mensajes no encontrados

tg store gaps repair <chat> [options]
ArgumentoObligatoriedadQué es
chatobligatoriochat por título completo o parcial, identificador, @username o me para Mensajes guardados.
OpciónQué hace
--limit <n>total de mensajes en esta reparación, 500 de forma predeterminada.
--max-gaps <n>como máximo este número de lagunas, 5 de forma predeterminada.
--repair-time <duration>tiempo disponible para la reparación, 30s de forma predeterminada. Predeterminado: 30s.
--page-size <n>mensajes por página del proveedor.
--pause <duration>pausa entre páginas del proveedor. Predeterminado: 1s.
--fingerprint <hash>rechazar si este plan de cobertura previamente revisado ha cambiado.
--catch-uppreparar la búsqueda local después de reparar; anula searchCatchUp.
--no-catch-upomitir la preparación de la búsqueda local después de reparar.
--catch-up-chunks <n>máximo de fragmentos locales que se preparan.
--catch-up-messages <n>máximo de mensajes almacenados que se leen para la preparación.
--catch-up-time <duration>tiempo de preparación dentro del tiempo restante de la reparación.
--backgroundreparar mediante el mecanismo existente de trabajos del almacenamiento; consultar store jobs show.

tg store jobs

sincronizaciones en segundo plano

tg store jobs list

sincronizaciones en segundo plano, recientes primero

tg store jobs list [options]
OpciónQué hace
--state <state>solo las tareas en este estado. Uno de: running, done, partial, failed, cancelled, died.

tg store jobs show

tarea indicada o la más reciente y datos de su chat ya guardados

tg store jobs show [job]
ArgumentoObligatoriedadQué es
jobopcionalidentificador que imprimió messages sync --background.

tg store jobs cancel

detiene la tarea tras la página actual; una sincronización posterior reanuda desde ahí

tg store jobs cancel <job>
ArgumentoObligatoriedadQué es
jobobligatorioidentificador de tarea.

tg store jobs retry

reintentar una tarea fallida o interrumpida como una nueva; la sincronización continúa donde se detuvo el archivo

tg store jobs retry [job] [options]
ArgumentoObligatoriedadQué es
jobopcionalid de la tarea.
OpciónQué hace
--failedcada chat cuya última tarea falló o se interrumpió.

tg store jobs clear

olvidar las tareas terminadas y borrar sus registros; se conserva la tarea en curso

Solo hace cambios en este equipo.

tg store jobs clear

tg store export

mensajes guardados de un chat, antiguos primero: --jsonl un mensaje por línea, --json un objeto { items, page, limit, hasMore }; nunca consulta el servicio

tg store export [chats] [options]
ArgumentoObligatoriedadQué es
chatsopcionalchat por título completo o parcial, identificador, @username o me para Mensajes guardados; varios con --to.
OpciónQué hace
--format <format>jsonl: mensaje por línea, el predeterminado con --output; markdown: transcripción por días con respuestas y reenvíos citados.
--since-time <time>solo a partir de esta fecha ISO 8601 o intervalo anterior como 30m / 2h / 1d.
--output <file>escribe líneas JSON o transcripción en un archivo nuevo, legible solo por ti.
--to <dir>escribe en esta carpeta un archivo por chat y un manifiesto; al repetirlo sobre ella, solo lo que cambió desde entonces.
--kind <kinds>con --to: todos los chats guardados de estos tipos, separados por comas: dialog, group, channel, saved.
--allcon --to: todos los chats guardados de esta cuenta.
--encryptcomprime y cifra con una contraseña, escrita en una solicitud oculta o pasada por stdin; nunca se guarda: si la pierdes, no se puede abrir el archivo.

tg store clear

elimina del archivo los chats abandonados y sus mensajes

tg store clear [options]
OpciónQué hace
--leftchats que esta cuenta abandonó; es lo único que elimina.
--allow-dangerousconfirma la eliminación irreversible; no se pueden descargar de nuevo chats abandonados.

tg store info

ruta, tamaño, esquema y filas del archivo local; no cambia nada

tg store info

tg store check

comprueba integridad, índices de búsqueda, disco y chats desactualizados

tg store check

tg store migrate

actualiza el esquema a esta versión y normaliza, indexa y extrae las raíces de los mensajes y notas anteriores

tg store migrate

tg store reindex

reconstruye el índice de palabras, su vocabulario de erratas, las raíces, el índice de palabras de los archivos y los índices de las notas a partir de lo guardado, sin perder nada

tg store reindex

tg store backup

copial archivo local mientras está en uso, sin sobrescribir

tg store backup <file> [options]
ArgumentoObligatoriedadQué es
fileobligatorioarchivo nuevo.
OpciónQué hace
--encryptcomprime y cifra con una contraseña, escrita en una solicitud oculta o pasada por stdin; nunca se guarda: si la pierdes, no se puede abrir el archivo.

tg store restore

restaura una copia; conserva al lado el archivo sustituido, sin eliminarlo

tg store restore <file>
ArgumentoObligatoriedadQué es
fileobligatorioarchivo creado por store backup; si se escribió con --encrypt, pide su contraseña.

tg store decrypt

abre un archivo escrito con --encrypt en un archivo nuevo; pide su contraseña

tg store decrypt <file> [options]
ArgumentoObligatoriedadQué es
fileobligatorioarchivo creado por store backup --encrypt o store export --encrypt.
OpciónQué hace
--output <file>archivo nuevo, legible solo por ti.

tg store repair

adapta cada tabla a la forma de esta versión sin eliminar nada: una tabla con una forma incorrecta se conserva como copia junto a una nueva

tg store repair [options]
OpciónQué hace
--dry-runindica qué haría, sin cambiar nada.

tg store reset

back the store up beside itself, then delete it and start an empty one at this build's schema; asks first, or --yes

tg store reset [options]
OpciónQué hace
--no-backupdelete the store without backing it up first.

tg store copies

tablas que store repair conservó como copias

tg store copies delete

elimina una copia conservada por store repair, indicada por su nombre exacto; rechaza cualquier otra tabla

tg store copies delete <name>
ArgumentoObligatoriedadQué es
nameobligatorionombre de la copia, tal como lo mostró store repair.

tg flood

las esperas que Telegram pidió respetar a este perfil y un bloqueo de sus escrituras

tg flood clear

olvidarlos, levantar el bloqueo y la regulación del ritmo del perfil una vez que Telegram ya no limite la cuenta; no cambia nada allí

tg flood clear

tg runs

ejecuciones registradas: qué hizo la herramienta y cuándo

tg runs list

ejecuciones registradas, recientes primero

tg runs list [options]
OpciónQué hace
--limit <n>cuántas mostrar. Predeterminado: 20.

tg runs show

una ejecución: qué fue, cómo terminó y qué falló; -v para cada evento

tg runs show <run-id>
ArgumentoObligatoriedadQué es
run-idobligatorioidentificador de tg runs list.

search recorded diagnostic metadata and events; no message contents

tg runs search [query] [options]
ArgumentoObligatoriedadQué es
queryopcionalcase-insensitive literal diagnostic text.
OpciónQué hace
--status <status>run outcome. Uno de: success, failed, partial, running.
--error-code <code>one stable error code.
--operation <name>one operation, such as messages.download.
--profile <name>one recorded profile.
--since-time <time>runs starting on or after an ISO time or 2h / 1d ago.
--limit <n>matches per page, at most 100. Por defecto: 20.
--page <n>result page. Por defecto: 1.

tg runs path

directorio de una ejecución

tg runs path <run-id>
ArgumentoObligatoriedadQué es
run-idobligatorioidentificador de tg runs list.

tg config

ajustes efectivos y origen de cada valor

tg config migrate

sustituir los ajustes de acceso antiguos por permisos, conservando los niveles efectivos de este archivo

Solo hace cambios en este equipo.

tg config migrate [options]
OpciónQué hace
--dry-runmostrar la migración sin escribir el archivo.

tg config show

perfil, perfiles existentes y ajustes con su origen

tg config show [options]
OpciónQué hace
--botajustes del bot del perfil en lugar de los de la cuenta personal.

tg config set

guarda un ajuste en la configuración

Solo hace cambios en este equipo.

tg config set <setting> <value> [options]
ArgumentoObligatoriedadQué es
settingobligatoriouno de: limit, timeoutMs, color, senderColors, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, requestsPerMinute, transcribeWith, speechModel, catchUpMarksRead, searchCatchUp, embeddingProvider, embeddingModel, embeddingBaseUrl, embeddingDims, analysisProvider, analysisModel, analysisBaseUrl, models, proxy, readOtherBots, updateCheck, skillHint, defaultProfile, searchStemmers.cyrillic, searchStemmers.latin, accountGroups..
valueobligatorionúmero, true o false; para allow, lista como send,reaction; para un grupo, tg:work,max:Alice,email:me@x.
OpciónQué hace
--defaultscambia los valores de todos los perfiles en lugar de solo este.
--personalsolo cuentas personales, sección personal del archivo.
--botsolo bots, sección bot del archivo.

tg config unset

elimina un ajuste de la configuración

Solo hace cambios en este equipo.

tg config unset <setting> [options]
ArgumentoObligatoriedadQué es
settingobligatoriouno de: limit, timeoutMs, color, senderColors, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, requestsPerMinute, transcribeWith, speechModel, catchUpMarksRead, searchCatchUp, embeddingProvider, embeddingModel, embeddingBaseUrl, embeddingDims, analysisProvider, analysisModel, analysisBaseUrl, models, proxy, readOtherBots, updateCheck, skillHint, defaultProfile, searchStemmers.cyrillic, searchStemmers.latin, accountGroups..
OpciónQué hace
--defaultscambia los valores de todos los perfiles en lugar de solo este.
--personalsolo cuentas personales, sección personal del archivo.
--botsolo bots, sección bot del archivo.

tg doctor

estado de la instalación, sin conectarse salvo con --online

tg doctor [options]
OpciónQué hace
--onlinetambién se conecta una vez y lee la cuenta, sin enviar.

tg doctor report

contenido de un informe de problema; no escribe nada

tg doctor report create

guarda un informe en un archivo e indica dónde enviarlo

tg doctor report create [options]
OpciónQué hace
--run <id>ejecución que incluir; la última fallida por defecto.
--output <file>destino; un archivo nuevo en la carpeta actual por defecto.

tg commands

comandos, opciones y códigos de salida en JSON; consulta una ruta de comando por llamada

tg commands schema

argv y esquemas de resultados de un comando, efectos, permisos y orientación sobre reintentos

tg commands schema <path>
ArgumentoObligatoriedadQué es
pathobligatoriouna ruta de comando, por ejemplo: stats messages show.

tg complete

autocompletado: tg complete zsh imprime el script que debe cargarse

tg complete [words]
ArgumentoObligatoriedadQué es
wordsopcional

tg upgrade

actualiza tg con su gestor de paquetes; --check solo comprueba

tg upgrade [options]
OpciónQué hace
--checkcomprueba si hay nueva versión sin instalar nada.

tg mcp

ofrece el perfil a un agente por MCP mediante stdin y stdout: claude mcp add tg -- tg mcp

tg mcp [options]
OpciónQué hace
--permission <key=level>sobrescribir un permiso solo para este servidor; repetir para más claves.
--confirm-sendya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil.
--allow-dangerousya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil.
--allow-sendobsoleta: deciden los permisos del perfil; se conserva para compatibilidad.
--allow-mark-readobsoleta: deciden los permisos del perfil.
--allow-deleteobsoleta: deciden los permisos del perfil.
--httpservir mediante HTTP en 127.0.0.1 para ChatGPT y Claude en el navegador, detrás de tu túnel.
--http-confirmation <mode>ya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil.
--port <port>puerto local para --http (predeterminado 8765).
--public-url <url>dirección https del túnel que usan las aplicaciones del navegador, p. ej. https://.ts.net.
--revokeolvida todos los inicios de sesión concedidos a aplicaciones del navegador; cada una debe volver a iniciar sesión.

tg mcp config

imprime la entrada mcpServers para Claude Desktop, Cursor y otros con rutas completas, sin escribir

tg mcp config [options]
OpciónQué hace
--permission <key=level>sobrescribir un permiso solo para este servidor; repetir para más claves.
--confirm-sendya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil.
--allow-dangerousya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil.
--allow-sendobsoleta: deciden los permisos del perfil; se conserva para compatibilidad.
--allow-mark-readobsoleta: deciden los permisos del perfil.
--allow-deleteobsoleta: deciden los permisos del perfil.

tg mcp setup

añade el servidor MCP local de este perfil a Codex o Claude Code

Solo hace cambios en este equipo.

tg mcp setup <client> [options]
ArgumentoObligatoriedadQué es
clientobligatoriocodex o claude-code.
OpciónQué hace
--allow-writesconfirma que este perfil ofrece herramientas de escritura.
--permission <key=level>sobrescribir un permiso solo para este servidor; repetir para más claves.
--confirm-sendya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil.
--allow-dangerousya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil.
--allow-sendobsoleta: deciden los permisos del perfil; se conserva para compatibilidad.
--allow-mark-readobsoleta: deciden los permisos del perfil.
--allow-deleteobsoleta: deciden los permisos del perfil.

tg mcp doctor

comprueba la conexión inicial MCP local y la lista de herramientas de este perfil

tg mcp doctor [options]
OpciónQué hace
--permission <key=level>sobrescribir un permiso solo para este servidor; repetir para más claves.
--confirm-sendya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil.
--allow-dangerousya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil.
--allow-sendobsoleta: deciden los permisos del perfil; se conserva para compatibilidad.
--allow-mark-readobsoleta: deciden los permisos del perfil.
--allow-deleteobsoleta: deciden los permisos del perfil.

tg skill

instrucciones para que un agente utilice la herramienta

tg skill show

imprime SKILL.md; tg skill install lo coloca donde lo buscan Claude Code, Codex y Gemini CLI

tg skill show [name]
ArgumentoObligatoriedadQué es
nameopcionalskill de tarea incluida: follow-ups, link-conversations.

tg skill install

guarda SKILL.md en ~/.claude/skills/tg-cli/ (Claude Code) y ~/.agents/skills/tg-cli/ (Codex, Gemini CLI)

tg skill install [options]
OpciónQué hace
--for <agents>agentes para los que instalar. Valores: claude, agents, all. Predeterminado: all.

Códigos de salida

Elige la rama según el código, no según el texto: el texto puede cambiar, el código no.

CódigoCuándo
0éxito
2validation_error
3configuration_error
4authentication_error
5permission_error
6not_found
7confirmation_required
8rate_limited
9timeout
10network_error
11provider_error
12provider_unavailable
13invalid_response
14outcome_unknown
130cancelled
1cualquier otro caso

0 y solo 0 significa que la operación se completó. 14 (outcome_unknown) significa que un mensaje puede haberse enviado: repítelo solo con el mismo --send-id, que Telegram usa para descartar una segunda copia.