# Telegram · Línea de comandos

Canonical page: https://phishdestroy.io/tgwitness/es/docs/reference/cli/

Buscar, leer el contexto, contabilizar la actividad y exportar mensajes guardados desde scripts y agentes, con salida en formato --json, códigos de salida estables y tokens de solo lectura con ámbito limitado.

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/es/llms.txt)

Translation coverage: this edition includes material from the English original.

Buscar, leer el contexto, contabilizar la actividad y exportar mensajes guardados desde scripts y agentes, con salida en formato --json, códigos de salida estables y tokens de solo lectura con ámbito limitado.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentación](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![Integraciones con archivos](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

[MCP de solo lectura](https://phishdestroy.io/tgwitness/es/docs/reference/mcp/) · [Búsqueda de texto completo](https://phishdestroy.io/tgwitness/es/docs/reference/search/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**Preview.** `tgwitness search`, `context`, `messages`, `stats` and `export` read saved observations for scripts and AI agents. They cannot send anything to Telegram, change settings or modify the signed journal. `tgwitness index` and `tgwitness backup` ([below](https://phishdestroy.io/tgwitness/es/docs/reference/cli/#index-and-backup)) work on a local data directory and need no token.

Con `--json`, la salida estándar (stdout) contiene exactamente un documento JSON (`export` escribe líneas JSON). El progreso, las sugerencias y los errores se envían a stderr. Los códigos de salida son estables:

| Código | Significado |
| --- | --- |
| `0` | Éxito, incluido un resultado vacío |
| `1` | Error: panel inaccesible, datos ilegibles, exportación interrumpida |
| `2` | Error de uso o solicitud no válida: fecha incorrecta, opción desconocida, índice de búsqueda desactivado |
| `3` | No disponible en este momento: el espacio de trabajo está abierto en un panel en ejecución, o el panel solicita que se vuelva a intentar más tarde (límite de frecuencia, tiempo de espera agotado). |
| `4` | Acceso denegado: token ausente, caducado o revocado; un chat fuera de su ámbito de aplicación; una herramienta que no lo permite. |

## Dos formas de leerlo

**A través del panel (`--url`).** El comando utiliza la misma API de archivo con ámbito que MCP. Crea una conexión en **Más herramientas → Integraciones → MCP**: elige espacios de trabajo y chats, herramientas y una fecha de caducidad, y luego copia el token una vez. La conexión es de solo lectura, está limitada a esos chats, tiene un límite de 60 solicitudes por minuto y puede revocarse o renovarse en cualquier momento. Los tokens de inicio de sesión del panel y las credenciales de Telegram no funcionan aquí.

```
export TGWITNESS_URL=https://panel.example.org      # default http://127.0.0.1:8787
export TGWITNESS_MCP_TOKEN=tgw_mcp_...              # or --token-file path
tgwitness search 'перевод карта' --json
```

Un panel remoto requiere HTTPS; el HTTP sin cifrar solo se acepta para `127.0.0.1`, `localhost` y `::1`. Se ignoran las variables de entorno de proxy y se rechazan las redirecciones, por lo que el token solo llega a la dirección que indiques.

**Directamente desde un espacio de trabajo detenido (`--data-dir`).** Lee el directorio de datos con acceso local completo, sin necesidad de un token. Úsalo en una copia del directorio de datos o mientras la recopilación esté detenida. Los registros firmados nunca se modifican; al igual que en el panel, al abrir un espacio de trabajo es posible que se actualicen sus índices derivados. Cuando el panel tiene el espacio de trabajo abierto, el comando finaliza con código `3`; léalo a través del panel. Si no `--data-dir`, `TGWITNESS_DATA`, `./data/live` se utiliza el directorio de datos de la instalación en la que se ejecuta el comando.

`--workspace ID` selecciona un espacio de trabajo (por defecto `default`). `tgwitness messages
--workspaces` muestra los que puedes leer.

## Comandos

| Comando | Resultado |
| --- | --- |
| `tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N]` | Se mostrarán primero los resultados más relevantes, incluyendo variantes de palabras, frases exactas entre comillas, dominios y `@username` ([sintaxis](https://phishdestroy.io/tgwitness/es/docs/reference/search/#search-syntax)) |
| `tgwitness search QUERY --exact [--before SEQ]` | Texto exacto, de más reciente a más antiguo, sin el índice |
| `tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ]` | Mensajes guardados dentro de un margen de diez ID de mensaje a cada lado |
| `tgwitness messages [--limit N] [--offset N]` | Chats que puedes leer |
| `tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ]` | Mensajes guardados del chat, ordenados de más reciente a más antiguo |
| `tgwitness messages CHAT_ID --message ID` | Cada versión guardada y cada registro de eliminación de un mensaje |
| `tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N]` | Estadísticas de actividad, a continuación |
| `tgwitness export [--chat ID] [--since] [--until] [--output FILE]` | Observaciones guardadas como líneas JSON en orden de registro. |

Las fechas son `2026-10-01` (medianoche UTC) o en formato ISO con la zona horaria, `2026-10-01T09:00+03:00`. Para `search`, `messages` y `export` se selecciona la hora de la observación. Las páginas admiten hasta 50 registros: sigue `next_offset` (`--offset`) para la búsqueda por orden de relevancia y `next_before` (`--before`) en otros lugares.

Ranked search stops at 1,000 results. The final page may be shorter than `--limit`. When more observations match, the last page says so (`truncated: true` with `--json`); narrow the query, chat or period.

Cada resultado de mensaje incluye `untrusted_content: true` , los ID del espacio de trabajo, del chat y del mensaje, la secuencia del diario, el hash del registro guardado y un enlace al panel. Las ediciones, los avisos de eliminación y `missing_on_recheck` son registros independientes. La cobertura en `stats` muestra los periodos a los que se refiere un resultado de búsqueda.

### Estadísticas de actividad

`stats` Cuenta las observaciones guardadas para un chat, un remitente o todos los chats incluidos en el ámbito de aplicación:

- mensajes por hora UTC y por día de la semana (empezando por el lunes), horas y días de mayor actividad;
- editados, eliminados y `missing_on_recheck` compartidos;
- remitentes con el recuento de mensajes y las horas del primer y último mensaje;
- los dominios más frecuentes y `@handles`, contados una vez por mensaje en todas sus versiones guardadas;
- Cobertura: `coverage.gap` registros y, para acceder a todo el espacio de trabajo, períodos sin señal de vida del colector conectado (`collector_liveness`).

El periodo selecciona **la hora del mensaje indicada por Telegram**. Los recuentos de horas y días de la semana ayudan a estimar la zona horaria del remitente. Las cifras se calculan a petición del diario y no se almacenan. Cada resultado indica el encabezado del diario que abarca cuando tu acceso abarca todo el espacio de trabajo. La lectura se detiene tras cinco segundos a través del panel, o tras `--timeout` segundos localmente (por defecto, 30); entonces `complete` es falso y `partial` indica el primer registro que no se ha leído. En ese caso, solo se contan los registros más recientes.

### Exportar

`export` Escribe un objeto JSON por cada observación guardada (mensajes nuevos, instantáneas, modificaciones, mensajes recuperados, avisos de eliminación, `missing_on_recheck` y registros de archivos multimedia guardados) en el orden del registro. Cada línea tiene los mismos campos que el resto de resultados, con el texto completo. Al `--output`, el archivo se guarda con un `.partial` nombre y solo se renombra tras el registro de finalización del panel; una exportación interrumpida no deja ningún archivo y sale con el código `1`. `--output` nunca sobrescribe un archivo existente. Con `--output` y `--json`, la salida estándar muestra un resumen: recuento de registros, última secuencia del diario y, para el acceso a todo el espacio de trabajo, el encabezado del diario.

Una exportación a través del panel requiere una conexión que permita **exportar mensajes (solo línea de comandos)** ; no está seleccionada por defecto. Este archivo es una copia de trabajo; para una entrega verificable, utiliza la exportación firmada en **Exportaciones** , que se comprueba con `python -m tgwitness.verify` .

El panel vuelve a comprobar el acceso antes de emitir cada registro, incluido el registro de finalización. Un acceso revocado o caducado da lugar a una exportación incompleta. Las lecturas diferidas de páginas comparten el límite del proceso de archivo con otras consultas y tienen un tiempo de espera limitado.

### Index and backup

These two commands read the data directory directly and take no token or `--url`.

| Comando | Resultado |
| --- | --- |
| `tgwitness index status [--workspace ID] [--data-dir DIR] [--json]` | Search index state of one workspace or, by default, every workspace: mode, `ready`, `building` or `not built`, indexed and journal head sequence. Works while the panel runs |
| `tgwitness index rebuild [--workspace ID] [--data-dir DIR] [--json]` | Rebuilds the index from the first journal record. Rewrites only the derived index, never the signed journal. Exits with code `3` while the panel has the workspace open. Nothing is built when the workspace keeps its index in memory or has search off |
| `tgwitness backup FOLDER [--data-dir DIR] [--json]` | Copies the whole data directory into a new or empty folder outside it while the panel keeps running, and writes `backup-manifest.json` with every file's SHA-256 and the journal heads |

`index` accepts `--workspace default` or a workspace ID; the default is `all`. The backup skips temporary exports, SQLite sidecar files and lock files. The folder holds the Telegram session and signing keys, so keep it as private as the data directory. [Backup, restore, and capacity](https://phishdestroy.io/tgwitness/es/docs/reference/deployment/#backup-restore-and-capacity) describes restoring and what the next start records.

## Habilidad del agente

[`.agents/skills/tgwitness-cli/SKILL.md`](https://github.com/phishdestroy/TgWitness/blob/main/.agents/skills/tgwitness-cli/SKILL.md) indica a un agente cómo utilizar estos comandos, cómo citar los registros y cómo tratar el texto capturado. Los agentes que lean `.agents/skills` lo cargan desde una copia del repositorio. Para Claude Code, copia la `tgwitness-cli` carpeta en `.claude/skills/` en tu proyecto o `~/.claude/skills/`.

## MCP y la línea de comandos

Ambos utilizan las mismas conexiones, comprobaciones de ámbito y límites. Los resultados de MCP se limitan a una página de 64 KiB, por lo que MCP no ofrece exportación masiva; la línea de comandos los transmite en tiempo real. `get_activity_stats` está disponible para ambos.
