Instalación

Instala el CLI con tu agente local o en la terminal. Es un paquete npm para Windows, macOS y Linux. El agente puede comprobar el ordenador, instalarlo y ayudarte a iniciar sesión.

Instalar con tu agente

Abre el bloque de abajo y copia la petición en tu agente. Después de iniciar sesión, comprueba tu cuenta y algunos chats. Descargar el historial antiguo es un paso aparte.

Configura tg en mi ordenador. Primero lee la guía: https://wirecat.dev/llms.mdx/docs/es/installation/content.md

Comprueba que tienes Node.js 22.16+ (rama 22.x) o 24+ y npm.

Instala con npm install -g @leemour/tg-cli (usa npm.cmd en Windows PowerShell). Comprueba que tg funciona por su nombre en tu terminal actual y en terminales nuevas. En Windows, consulta la carpeta de instalación con npm.cmd prefix -g; añádela al PATH del usuario si falta, conserva las entradas existentes y actualiza el PATH de tu propia terminal. No supongas que npm ha actualizado una terminal que ya estaba abierta. En macOS/Linux, comprueba npm prefix -g y su carpeta bin sin sobrescribir la configuración del shell. Si PowerShell bloquea el script generado, usa el ejecutable .cmd y la recuperación documentada sin cambiar la política de ejecución permanente.

Antes de iniciar sesión, ejecuta tg skill install --for all. Lee tg --help, tg commands --json y tg skill show; carga el skill instalado y verifica que tu agente lo utiliza.

Usa la configuración guiada si el cli instalado la admite; si no, sigue la guía de inicio de sesión. Dime que la configuración tarda unos cinco minutos y que descargar el historial es un paso separado. Introduciré los códigos y contraseñas localmente o escanearé el QR.

Comprueba tg --version, ejecuta tg doctor, verifica la cuenta conectada y muestra los primeros cinco chats.

npm install -g @leemour/tg-cli
tg skill install --for all
tg --version
tg doctor

& ([scriptblock]::Create((Invoke-RestMethod 'https://wirecat.dev/install.ps1'))) -Tool tg -Agent all

tg setup --agent all

tg account show
tg chats list --limit 5
tg inbox --limit 5

Probar las primeras tareas → · Cómo formular peticiones

Instalación manual y detalles técnicos

tg es un comando que se instala como un paquete npm normal. No compila nada durante la instalación: SQLite viene incluido en el entorno de ejecución, por lo que no hay módulos nativos que compilar. Tampoco inicia procesos en segundo plano por su cuenta. Una instalación global con npm puede instalar las instrucciones del agente y, en Windows, reparar el PATH del usuario. Nunca inicia sesión ni lee chats durante la instalación.

RequisitosCopy Anchor Link

• Node.js 22.16 o posterior. También es compatible con Bun.
• Linux, macOS o Windows.
• Tu propia aplicación de Telegram, registrada en my.telegram.org. tg la solicita al iniciar sesión por primera vez y puede registrarla por ti (sesiones).

InstalaciónCopy Anchor Link

npm install -g --allow-scripts=@leemour/tg-cli --foreground-scripts @leemour/tg-cli
# The global install puts the skill in .agents and .claude. Then: tg setup

pnpm add -g @leemour/tg-cli
bun add -g @leemour/tg-cli

El paquete se llama @leemour/tg-cli; el comando que instala es tg.

Para probarlo sin instalarlo:

npx @leemour/tg-cli --help

Comprueba que funciona:

tg --version
tg --help
tg doctor        # where its files are, and whether a login exists; connects to nothing

Primer usoCopy Anchor Link

tg --help muestra la configuración y las instrucciones para agentes nada más instalar. tg skill show funciona antes de iniciar sesión: el agente debe leerlo antes de conectar Telegram. tg commands --json enumera comandos y opciones. Estas indicaciones funcionan incluso si el gestor de paquetes omite los scripts de instalación.

En una terminal local, ejecuta:

tg setup --agent codex
tg setup --help              # examples, login choices and Windows instructions

Elige codex, cursor, claude, gemini, all o none. Sin --agent, pregunta en una terminal; con --json o sin terminal usa none. Reserva unos cinco minutos para registrar la aplicación, iniciar sesión, comprobar los primeros cinco chats e instalar la skill. Descargar historial es aparte y puede tardar más: elige chat y cantidad antes de ejecutar el comando store fetch sugerido. Setup no inicia servicios en segundo plano.

tg setup --app browser muestra las instrucciones de registro manual; --method phone inicia sesión por teléfono en vez de QR. El código de registro de my.telegram.org y el código de acceso a la cuenta corresponden a pasos distintos. Repetir setup comprueba la sesión existente sin volver a iniciar sesión. Si el acceso se interrumpió o Telegram terminó la sesión, completa primero tg session start y repite setup. Consulta sesiones.

Sin instalación global, usa npm exec --yes --package=@leemour/tg-cli -- tg setup --agent codex. Setup propone los comandos siguientes de la misma forma.

Windows: un comando de instalaciónCopy Anchor Link

En PowerShell, con Node.js 22.16+ o 24+ instalado:

& ([scriptblock]::Create((Invoke-RestMethod 'https://wirecat.dev/install.ps1'))) -Tool tg -Agent all

El instalador instala el paquete npm, conserva las entradas del PATH del usuario, añade una sola vez la carpeta de comandos de npm, actualiza el PATH de la ventana actual de PowerShell e instala la skill antes del acceso. Comprueba que tg arranca sin indicar su ruta. -Agent codex|cursor|claude|gemini|all|none elige dónde se guarda la skill; all, por defecto, instala ambos directorios admitidos. Repetir la instalación actualiza la skill sin duplicar PATH. También lo hace cuando los scripts de npm están desactivados.

La política de ejecución de PowerShell no cambia. El instalador elimina solo el lanzador tg.ps1 generado por npm para este paquete y conserva tg.cmd, de modo que tg funciona con una política restrictiva. Si encuentra un script ajeno con ese nombre, lo conserva e informa del conflicto.

La instalación global de npm también repara el PATH persistente de Windows e instala ambas skills cuando se permite su script postinstall:

npm.cmd install -g --allow-scripts=@leemour/tg-cli --foreground-scripts @leemour/tg-cli

Las versiones nuevas de npm pueden omitir los scripts salvo que se autoricen. --ignore-scripts también omite este. El instalador PowerShell es la vía principal en Windows porque actualiza tanto la terminal actual como el PATH persistente; un proceso hijo de npm no puede modificar el entorno de su padre. Los agentes iniciados antes de instalar deben actualizar el PATH de su terminal a partir del entorno de usuario y equipo, sin pedir al usuario que lo edite.

El script global solo se ejecuta en una instalación global de npm, nunca en dependencias de proyectos ni con npx. TG_INSTALL_AGENT=codex|cursor|claude|gemini|all|none selecciona la skill; none la desactiva. El agente lee tg skill show y comprueba su skill instalada antes de guiar el acceso a la cuenta. No hace falta un ejecutable separado para Windows.

Los primeros comandos de lectura están en primeros pasos.

git clone https://github.com/leemour/tg-cli.git
cd tg-cli
pnpm install
pnpm build

Dónde se guardan los archivosCopy Anchor Link

Hay tres directorios que siguen las convenciones del sistema operativo y otros dos compartidos:

~ es tu carpeta personal. En Windows, pega %APPDATA% o %LOCALAPPDATA% en la barra de direcciones del Explorador. <profile> es el nombre del perfil, normalmente default. Estas son las rutas predeterminadas; tg doctor muestra las rutas reales y sus cambios.

• Configuración: se guarda en config.json. Las credenciales de la aplicación Telegram normalmente van al llavero del sistema; credentials.json se usa si el llavero no está disponible.

• Datos de la cuenta y actividad: la tabla muestra las rutas completas de la sesión, las ejecuciones, los envíos, los destinatarios permitidos y la posición de lectura. Las descargas en segundo plano y el bloqueo del servidor también se guardan en el directorio de estado.
• Archivo local: se comparte con otros CLI de mensajería que usan la misma biblioteca, como max-cli. Consulta archivo local.
• Modelos de voz: solo se descargan cuando lo solicitas (tg models audio download), para messages transcribe --local.

tg doctor muestra las rutas exactas en este equipo.

Puedes cambiar cada ubicación con una variable: TG_CONFIG_DIR, TG_STATE_DIR, TG_CACHE_DIR, MESSAGING_STORE (el propio archivo de la base de datos) y CLI_COMMON_CACHE_DIR (los modelos).

⚠ TG_CONFIG_DIR, TG_STATE_DIR y TG_CACHE_DIR también cambian la entrada del almacén de claves. Una sesión creada con alguna de estas variables deja de ser visible si la quitas, y viceversa: el comando responde "no session" aunque hayas iniciado sesión. Úsalas siempre o nunca. tg config show indica si alguna está definida.

ActualizaciónCopy Anchor Link

tg upgrade            # with the package manager that installed tg: npm, pnpm or bun
tg upgrade --check    # only say whether a newer version exists; installs nothing

tg upgrade también reinicia cualquier serve en segundo plano que encuentre activo, para que el servidor no siga usando el código anterior. Nunca se ejecuta por su cuenta.

Resultado JSON de la actualizaciónCopy Anchor Link

tg upgrade --check --json informa de las versiones actual y disponible sin instalar. El resultado común contiene current, latest, newer, installer, command, updated y restarted: los perfiles cuyos servidores se reiniciaron después de actualizar. Las comprobaciones, versiones sin cambios y actualizaciones sin reinicio devuelven una lista vacía; los campos anteriores se conservan. Telegram mantiene su política de reinicio de servidores administrados; los que requieren reinicio manual se indican en stderr. Los scripts que comprueban el conjunto exacto de claves JSON deben aceptar restarted en todos los casos.

Una vez al día, en una terminal, tg avisa por stderr si hay una versión más reciente en npm. No muestra el aviso con --json, en una tubería, con --quiet ni en CI. Para desactivarlo: tg config set updateCheck false --defaults, o TG_NO_UPDATE_CHECK=1.

Desde el código fuente: git pull && pnpm install && pnpm build. Con npx: npx @leemour/tg-cli@latest.

DesinstalaciónCopy Anchor Link

Eliminar el comando no elimina tus datos. Cierra sesión primero, mientras tg sigue instalado:

tg server uninstall                  # if you installed the background unit; stop it first
tg session end                       # logs out on Telegram's side and deletes the session file
npm uninstall -g @leemour/tg-cli
rm -rf ~/.config/tg-cli ~/.local/share/tg-cli ~/.cache/tg-cli

tg session end no elimina el identificador ni el hash de la aplicación del almacén de claves. Están en el servicio tg-cli; elimina esa entrada con la herramienta de tu sistema si también quieres borrarlos.

El archivo local se comparte con otras herramientas. Elimina ~/.local/share/cli-messaging/ solo si ninguna otra lo utiliza: contiene los mensajes que todas ellas han leído.

Siguiente pasoCopy Anchor Link

Primeros pasos: iniciar sesión y ejecutar los primeros comandos.