# Telegram · Linha de comando

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

Pesquise, leia o contexto, conte atividades e exporte mensagens salvas a partir de scripts e agentes, com saída no formato --json, códigos de saída estáveis e tokens de leitura exclusiva com escopo definido.

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

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

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

Pesquise, leia o contexto, conte atividades e exporte mensagens salvas a partir de scripts e agentes, com saída no formato --json, códigos de saída estáveis e tokens de leitura exclusiva com escopo definido.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentação](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![Integrações com arquivos](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

[MCP somente leitura](https://phishdestroy.io/tgwitness/pt/docs/reference/mcp/) · [Pesquisa de texto completo](https://phishdestroy.io/tgwitness/pt/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/pt/docs/reference/cli/#index-and-backup)) work on a local data directory and need no token.

Com `--json`, a saída padrão (stdout) contém exatamente um documento JSON (`export` grava linhas JSON). O progresso, as dicas e os erros são direcionados para o stderr. Os códigos de saída são estáveis:

| Código | Significado |
| --- | --- |
| `0` | Sucesso, incluindo um resultado vazio |
| `1` | Falha: painel inacessível, dados ilegíveis, exportação interrompida |
| `2` | Erro de uso ou solicitação inválida: data incorreta, opção desconhecida, índice de pesquisa desativado |
| `3` | Indisponível no momento: o espaço de trabalho está aberto em um painel em execução, ou o painel solicita que se tente novamente mais tarde (limite de taxa, tempo limite) |
| `4` | Acesso negado: token ausente, expirado ou revogado; um chat fora do escopo; uma ferramenta que não permite |

## Duas maneiras de ler

**Por meio do painel (`--url`).** O comando utiliza a mesma API de arquivo com escopo que MCP. Crie uma conexão em **Mais ferramentas → Integrações → MCP**: escolha espaços de trabalho e chats, ferramentas e um prazo de validade, depois copie o token uma vez. A conexão é somente para leitura, limitada a esses chats, com restrição de taxa de 60 solicitações por minuto e pode ser revogada ou renovada a qualquer momento. Tokens de login do painel e credenciais do Telegram não funcionam aqui.

```
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
```

Um painel remoto requer HTTPS; o HTTP simples é aceito apenas para `127.0.0.1`, `localhost` e `::1`. Variáveis de ambiente de proxy são ignoradas e redirecionamentos são recusados, de modo que o token chegue apenas ao endereço que você fornecer.

**Diretamente de um espaço de trabalho parado (`--data-dir`).** Lê o diretório de dados com acesso local total, sem um token. Use-o em uma cópia de um diretório de dados ou enquanto a coleta estiver parada. Registros assinados nunca são alterados; assim como no painel, abrir um espaço de trabalho pode atualizar seus índices derivados. Quando o painel tem o espaço de trabalho aberto, o comando sai com código `3`; leia pelo painel, em vez disso. Sem `--data-dir`, `TGWITNESS_DATA`, `./data/live` ou o diretório de dados da instalação que está executando o comando é utilizado.

`--workspace ID` seleciona um espaço de trabalho (padrão `default`). `tgwitness messages
--workspaces` lista aqueles que você pode ler.

## Comandos

| Comando | Resultado |
| --- | --- |
| `tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N]` | Melhores correspondências primeiro, incluindo formas de palavras, frases exatas entre aspas, domínios e `@username` ([sintaxe](https://phishdestroy.io/tgwitness/pt/docs/reference/search/#search-syntax)) |
| `tgwitness search QUERY --exact [--before SEQ]` | Texto exato, do mais recente ao mais antigo, sem o índice |
| `tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ]` | Mensagens salvas dentro de dez IDs de mensagem de cada lado |
| `tgwitness messages [--limit N] [--offset N]` | Conversas que você pode ler |
| `tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ]` | Mensagens salvas do chat, com as mais recentes em primeiro lugar |
| `tgwitness messages CHAT_ID --message ID` | Cada versão salva e registro de exclusão de uma mensagem |
| `tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N]` | Estatísticas de atividade, abaixo |
| `tgwitness export [--chat ID] [--since] [--until] [--output FILE]` | Observações salvas como linhas JSON na ordem do registro |

As datas são `2026-10-01` (meia-noite UTC) ou horários ISO com fuso horário, `2026-10-01T09:00+03:00`. Para `search`, `messages` e `export` eles selecionam a hora da observação. As páginas comportam até 50 registros: siga `next_offset` (`--offset`) para busca por classificação e `next_before` (`--before`) em outros 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 mensagem contém `untrusted_content: true` , os IDs do espaço de trabalho, do chat e da mensagem, a sequência do diário, o hash do registro salvo e um link para o painel. Edições, avisos de exclusão e `missing_on_recheck` são registros separados. A cobertura em `stats` mostra os períodos aos quais um resultado de pesquisa se refere.

### Estatísticas de atividade

`stats` Conta as observações salvas para um chat, um remetente ou todos os chats no escopo:

- mensagens por hora UTC e por dia da semana (começando pela segunda-feira), horários e dias de maior movimento;
- editados, excluídos e `missing_on_recheck` compartilhamentos;
- remetentes com contagem de mensagens e horários da primeira e da última mensagem;
- os domínios mais frequentes e `@handles`, contados uma vez por mensagem em todas as suas versões salvas;
- cobertura: `coverage.gap` registros e, para acesso a todo o espaço de trabalho, períodos sem um sinal de vida do coletor conectado (`collector_liveness`).

O período seleciona **a hora da mensagem informada pelo Telegram**. As contagens de horas e dias da semana ajudam a estimar o fuso horário do remetente. Os números são calculados mediante solicitação do diário e não são armazenados. Cada resultado indica o cabeçalho do diário que abrange quando seu acesso abrange o espaço de trabalho. A leitura é interrompida após cinco segundos no painel ou após `--timeout` segundos localmente (padrão 30); então `complete` é falso e `partial` indica o primeiro registro que não foi lido. Nesse caso, apenas os registros mais recentes são contados.

### Exportar

`export` grava um objeto JSON por observação salva (novas mensagens, capturas de tela, edições, mensagens recuperadas, avisos de exclusão, `missing_on_recheck` e registros de mídia salvos) na ordem do diário. Cada linha possui os mesmos campos dos demais resultados, com o texto completo. Com `--output`, o arquivo é gravado com um `.partial` nome e é renomeado somente após o registro de conclusão do painel; uma exportação interrompida não deixa nenhum arquivo e encerra com o código `1`. `--output` nunca sobrescreve um arquivo existente. Com `--output` e `--json`, a saída padrão (stdout) exibe um resumo: contagem de registros, última sequência do diário e, para acesso a toda a área de trabalho, o cabeçalho do diário.

Uma exportação pelo painel requer uma conexão que permita **mensagens de exportação (somente linha de comando)** ; essa opção não está selecionada por padrão. Este arquivo é uma cópia de trabalho; para uma transferência verificável, use a exportação assinada em **Exportações** , que é verificada por `python -m tgwitness.verify` .

O painel verifica novamente o acesso antes de emitir cada registro, incluindo o registro de conclusão. O acesso revogado ou expirado resulta em uma exportação incompleta. As leituras de página diferidas compartilham o limite do processador de arquivos com outras consultas e têm um tempo 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/pt/docs/reference/deployment/#backup-restore-and-capacity) describes restoring and what the next start records.

## Habilidade do agente

[`.agents/skills/tgwitness-cli/SKILL.md`](https://github.com/phishdestroy/TgWitness/blob/main/.agents/skills/tgwitness-cli/SKILL.md) explica a um agente como usar esses comandos, como citar registros e como tratar o texto capturado. Agentes que leem `.agents/skills` carregam-no a partir de um checkout do repositório. Para o Claude Code, copie a `tgwitness-cli` pasta para `.claude/skills/` dentro do seu projeto ou `~/.claude/skills/`.

## MCP e a linha de comando

Ambos utilizam as mesmas conexões, verificações de escopo e limites. Os resultados do MCP estão limitados a uma página de 64 KiB; portanto, o MCP não oferece exportação em massa; a linha de comando transmite os dados em fluxo contínuo. `get_activity_stats` está disponível para ambos.
