> ## 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.

# Archives (@archive)

> Lists, reads, extracts and creates zip and tar archives safely: zip-slip protection, symlink escapes refused, entry and size limits enforced on the real stream.

The **`@archive`** tool handles the bundles an agent downloads or ships — **zip, tar, tar.gz/tgz and tar.bz2** — without a shell and without the classic traps: an entry named `../../etc/passwd`, an absolute path, a symlink pointing outside the destination, or a 10 GB "bomb" declared as 1 KB.

***

## Subcommands

```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"]}}' />
```

| Verb | Arguments | What it does |
| - | - | - |
| `list` | `file`, `limit?` (500) | entries with kind, size and link target, plus totals |
| `read` | `file`, `entry`, `max_bytes?` (64 KiB) | one entry's text without extracting; binary entries are reported, not dumped |
| `extract` | `file`, `to`, `overwrite?`, `max_entries?` (10000), `max_total_bytes?` (1 GiB), `max_entry_bytes?` (256 MiB) | extracts under `to`; existing files are kept unless `overwrite: true` |
| `create` | `file`, `paths[]`, `base?` (`.`), `overwrite?` | builds a `.zip` or `.tar.gz`/`.tgz` by extension from workspace paths, sorted deterministically, `.git` excluded |

***

## Safety

* **Zip-slip**: absolute names, drive letters and `..` escapes are refused; every destination is resolved after symlinks and must stay under `to`, including when an already-materialized ancestor is a symlink leading out.
* **Links**: symlink and hard-link entries whose target resolves outside `to` are refused.
* **Limits** are enforced on the bytes actually read, not on the declared size; a refused entry leaves nothing behind and the report says how far extraction got.
* Files are created with `0600`/`0700` and `O_EXCL`, so a race cannot turn a refusal into an overwrite.
* `list`/`read` are read-only; `extract`/`create` are mutations and go through the coder security gate.

> [!NOTE]
>
> xz archives are not supported (no decoder in the standard library); the error names the supported formats.


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