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ón | Qué hace |
|---|---|
-V, --version | muestra el número de versión. |
-v, --verbose | añade detalles: -v muestra identificadores, -vv todos los datos conocidos. Valor predeterminado: 0. |
--json | salida para programas: un único valor JSON por stdout, nada más. |
--agent-json | JSON para agentes de IA: muestra los controles invisibles; --json normal conserva el texto. |
--jsonl | salida para programas: un objeto JSON por línea, para flujos y jq. |
--quiet | oculta los mensajes de diagnóstico, pero sigue mostrando fallos. |
--trace | registros de la conexión por stderr; nunca el contenido de mensajes. |
--debug | ante 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. |
--offline | responde desde lo guardado sin conectarse; falla si no hay datos. |
--no-input | no 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. |
--brief | mensajes y correo encontrados solo con referencia, título, hora, remitente y fragmento. |
--full | mensajes y correo encontrados con su texto completo y todos los campos del proveedor. |
--dry-run | previsualizar los argumentos analizados y los permisos antes de ejecutar la acción. |
--yes | omite la confirmación que el nivel ask exige antes de escribir. |
--record | guarda esta ejecución: identificadores y tiempos, nunca contenido. |
--no-record | no 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]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
method | opcional | método de acceso. Valores: qr, phone. Predeterminado: qr. |
| Opción | Qué 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. |
--sms | acceso 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 endtg setup
configura Telegram y conecta tu agente
Changes something in Telegram.
tg setup [options]| Opción | Qué 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 listtg 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ón | Qué hace |
|---|---|
--show-phone | muestra 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ón | Qué 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 listtg 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ón | Qué hace |
|---|---|
--others | todas 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 listtg models audio download
descarga un modelo y verifica el sha256 esperado por esta versión
tg models audio download <model>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 listtg models text download
descarga un modelo vectorial y comprueba el sha256 esperado por la versión
tg models text download <model> [options]| Opción | Qué hace |
|---|---|
--accept-terms | acepta 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>| Argumento | Obligatoriedad | Qué es |
|---|---|---|
provider | obligatorio | openai, 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>| Argumento | Obligatoriedad | Qué es |
|---|---|---|
provider | obligatorio | openai, 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ón | Qué hace |
|---|---|
--events | incluye 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 servetg 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 starttg server stop
detiene serve de este perfil mediante su unidad, si la utiliza
tg server stoptg server restart
lo detiene y vuelve a iniciarlo
tg server restarttg server status
si serve está activo para el perfil, desde cuándo, quién lo inició y unidad si existe
tg server statustg server logs
últimos registros de serve, desde systemd o su archivo de registros
tg server logs [options]| Opción | Qué 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 installtg server uninstall
elimina la unidad del perfil; detenla primero
tg server uninstalltg store
archivo local de mensajes
tg store status
por chat: cantidad guardada, más antiguo y reciente, y tramos completos
tg store status [chat]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
chat | opcional | chat 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>| Argumento | Obligatoriedad | Qué es |
|---|---|---|
chat | obligatorio | chat 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]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
chat | obligatorio | chat por título completo o parcial, identificador, @username o me para Mensajes guardados. |
| Opción | Qué 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-up | preparar la búsqueda local después de reparar; anula searchCatchUp. |
--no-catch-up | omitir 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. |
--background | reparar 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ón | Qué 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]tg store jobs cancel
detiene la tarea tras la página actual; una sincronización posterior reanuda desde ahí
tg store jobs cancel <job>| Argumento | Obligatoriedad | Qué es |
|---|---|---|
job | obligatorio | identificador 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]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
job | opcional | id de la tarea. |
| Opción | Qué hace |
|---|---|
--failed | cada 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 cleartg 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]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
chats | opcional | chat por título completo o parcial, identificador, @username o me para Mensajes guardados; varios con --to. |
| Opción | Qué 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. |
--all | con --to: todos los chats guardados de esta cuenta. |
--encrypt | comprime 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ón | Qué hace |
|---|---|
--left | chats que esta cuenta abandonó; es lo único que elimina. |
--allow-dangerous | confirma 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 infotg store check
comprueba integridad, índices de búsqueda, disco y chats desactualizados
tg store checktg 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 migratetg 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 reindextg store backup
copial archivo local mientras está en uso, sin sobrescribir
tg store backup <file> [options]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
file | obligatorio | archivo nuevo. |
| Opción | Qué hace |
|---|---|
--encrypt | comprime 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>| Argumento | Obligatoriedad | Qué es |
|---|---|---|
file | obligatorio | archivo 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]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
file | obligatorio | archivo creado por store backup --encrypt o store export --encrypt. |
| Opción | Qué 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ón | Qué hace |
|---|---|
--dry-run | indica 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ón | Qué hace |
|---|---|
--no-backup | delete 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>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 cleartg runs
ejecuciones registradas: qué hizo la herramienta y cuándo
tg runs list
ejecuciones registradas, recientes primero
tg runs list [options]| Opción | Qué 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>tg runs search
search recorded diagnostic metadata and events; no message contents
tg runs search [query] [options]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
query | opcional | case-insensitive literal diagnostic text. |
| Opción | Qué 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>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ón | Qué hace |
|---|---|
--dry-run | mostrar la migración sin escribir el archivo. |
tg config show
perfil, perfiles existentes y ajustes con su origen
tg config show [options]| Opción | Qué hace |
|---|---|
--bot | ajustes 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]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
setting | obligatorio | uno 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.. |
value | obligatorio | número, true o false; para allow, lista como send,reaction; para un grupo, tg:work,max:Alice,email:me@x. |
| Opción | Qué hace |
|---|---|
--defaults | cambia los valores de todos los perfiles en lugar de solo este. |
--personal | solo cuentas personales, sección personal del archivo. |
--bot | solo 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]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
setting | obligatorio | uno 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ón | Qué hace |
|---|---|
--defaults | cambia los valores de todos los perfiles en lugar de solo este. |
--personal | solo cuentas personales, sección personal del archivo. |
--bot | solo bots, sección bot del archivo. |
tg doctor
estado de la instalación, sin conectarse salvo con --online
tg doctor [options]| Opción | Qué hace |
|---|---|
--online | tambié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ón | Qué 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>| Argumento | Obligatoriedad | Qué es |
|---|---|---|
path | obligatorio | una ruta de comando, por ejemplo: stats messages show. |
tg complete
autocompletado: tg complete zsh imprime el script que debe cargarse
tg complete [words]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
words | opcional |
tg upgrade
actualiza tg con su gestor de paquetes; --check solo comprueba
tg upgrade [options]| Opción | Qué hace |
|---|---|
--check | comprueba 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ón | Qué hace |
|---|---|
--permission <key=level> | sobrescribir un permiso solo para este servidor; repetir para más claves. |
--confirm-send | ya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil. |
--allow-dangerous | ya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil. |
--allow-send | obsoleta: deciden los permisos del perfil; se conserva para compatibilidad. |
--allow-mark-read | obsoleta: deciden los permisos del perfil. |
--allow-delete | obsoleta: deciden los permisos del perfil. |
--http | servir 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. |
--revoke | olvida 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ón | Qué hace |
|---|---|
--permission <key=level> | sobrescribir un permiso solo para este servidor; repetir para más claves. |
--confirm-send | ya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil. |
--allow-dangerous | ya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil. |
--allow-send | obsoleta: deciden los permisos del perfil; se conserva para compatibilidad. |
--allow-mark-read | obsoleta: deciden los permisos del perfil. |
--allow-delete | obsoleta: 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]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
client | obligatorio | codex o claude-code. |
| Opción | Qué hace |
|---|---|
--allow-writes | confirma que este perfil ofrece herramientas de escritura. |
--permission <key=level> | sobrescribir un permiso solo para este servidor; repetir para más claves. |
--confirm-send | ya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil. |
--allow-dangerous | ya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil. |
--allow-send | obsoleta: deciden los permisos del perfil; se conserva para compatibilidad. |
--allow-mark-read | obsoleta: deciden los permisos del perfil. |
--allow-delete | obsoleta: 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ón | Qué hace |
|---|---|
--permission <key=level> | sobrescribir un permiso solo para este servidor; repetir para más claves. |
--confirm-send | ya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil. |
--allow-dangerous | ya no se usa — las operaciones de escritura no muestran un formulario; deciden los permisos del perfil. |
--allow-send | obsoleta: deciden los permisos del perfil; se conserva para compatibilidad. |
--allow-mark-read | obsoleta: deciden los permisos del perfil. |
--allow-delete | obsoleta: 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]| Argumento | Obligatoriedad | Qué es |
|---|---|---|
name | opcional | skill 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ón | Qué 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ódigo | Cuándo |
|---|---|
0 | éxito |
2 | validation_error |
3 | configuration_error |
4 | authentication_error |
5 | permission_error |
6 | not_found |
7 | confirmation_required |
8 | rate_limited |
9 | timeout |
10 | network_error |
11 | provider_error |
12 | provider_unavailable |
13 | invalid_response |
14 | outcome_unknown |
130 | cancelled |
1 | cualquier 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.