> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Arquivos compactados (@archive)

> Lista, lê, extrai e cria arquivos zip e tar com segurança: proteção contra zip-slip, symlinks que escapam recusados, limites de entradas e tamanho aplicados no stream real.

O tool **`@archive`** cuida dos pacotes que um agente baixa ou entrega — **zip, tar, tar.gz/tgz e tar.bz2** — sem shell e sem as armadilhas clássicas: uma entrada chamada `../../etc/passwd`, um caminho absoluto, um symlink apontando para fora do destino, ou uma "bomba" de 10 GB declarada como 1 KB.

***

## Subcomandos

```text theme={"system"}
<tool_call name="@archive" args='{"cmd":"list","args":{"file":"bundle.tar.gz"}}' />
<tool_call name="@archive" args='{"cmd":"read","args":{"file":"bundle.zip","entry":"README.md"}}' />
<tool_call name="@archive" args='{"cmd":"extract","args":{"file":"bundle.zip","to":"./vendor-src"}}' />
<tool_call name="@archive" args='{"cmd":"create","args":{"file":"release.tar.gz","paths":["dist","README.md"]}}' />
```

| Verbo | Argumentos | O que faz |
| - | - | - |
| `list` | `file`, `limit?` (500) | entradas com tipo, tamanho e alvo do link, mais totais |
| `read` | `file`, `entry`, `max_bytes?` (64 KiB) | o texto de uma entrada sem extrair; entradas binárias são reportadas, não despejadas |
| `extract` | `file`, `to`, `overwrite?`, `max_entries?` (10000), `max_total_bytes?` (1 GiB), `max_entry_bytes?` (256 MiB) | extrai sob `to`; arquivos existentes são mantidos salvo `overwrite: true` |
| `create` | `file`, `paths[]`, `base?` (`.`), `overwrite?` | monta um `.zip` ou `.tar.gz`/`.tgz` pela extensão a partir de caminhos do workspace, ordenados de forma determinística, `.git` excluído |

***

## Segurança

* **Zip-slip**: nomes absolutos, letras de unidade e escapes `..` são recusados; todo destino é resolvido após symlinks e precisa ficar sob `to`, inclusive quando um ancestral já materializado é um symlink que leva para fora.
* **Links**: entradas symlink e hard link cujo alvo resolve para fora de `to` são recusadas.
* **Limites** valem sobre os bytes realmente lidos, não sobre o tamanho declarado; uma entrada recusada não deixa nada para trás e o relatório diz até onde a extração chegou.
* Arquivos são criados com `0600`/`0700` e `O_EXCL`, então uma corrida não transforma uma recusa em sobrescrita.
* `list`/`read` são somente leitura; `extract`/`create` são mutações e passam pelo gate de segurança do coder.

> [!NOTE]
>
> Arquivos xz não são suportados (sem decoder na biblioteca padrão); o erro nomeia os formatos suportados.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.