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

# List Archive

> List files inside a ZIP archive. Returns sorted normalized paths with compressed and uncompressed sizes. Optionally filter by folder prefix or substring, then page with offset and limit.

`transform.archive-list` reads a ZIP archive and returns a deterministic list of
files. Use it to discover paths before [Extract Archive File](/steps/transform/archive-extract),
or to page through a large bundle without unpacking it.

ZIP is the only accepted archive format in this version. Directories and junk
paths are omitted. Matching entries are sorted by normalized path, then
`offset` / `limit` paginate that sorted list. `total` is the match count
**before** paging, so you can loop until you have seen every entry.

Point `archive` at a workflow file input or a previous step that produced a
trusted file (including another extract of a nested ZIP). Nested ZIP files stay
opaque `application/zip` files until you list or extract them in a later step.

## List, extract, then parse

Typical composition: list the archive, iterate entries, extract one path, then
parse the extracted file. The extract output is a file — pass the **whole
output** into Parse, Vision, or another archive step:

```yaml theme={null}
inputs:
  - name: bundle
    type: file

steps:
  - name: list
    type: transform.archive-list
    with:
      archive: "{{ input.bundle }}"
      prefix: invoices/

  - name: each
    type: control.foreach
    items: "{{ steps.list.output.entries }}"
    as: item
    steps:
      - name: extract
        type: transform.archive-extract
        with:
          archive: "{{ input.bundle }}"
          path: "{{ item.path }}"
      - name: parse
        type: ai.parse
        with:
          input: "{{ steps.extract.output }}"
```

The same body works under `control.parallel_map` (independent iterations, `concurrency` default 5, max 50). Nested ZIP example: extract `nested/packet.zip`, then list or search that extract output.

`control.parallel_map` can replace `foreach` when iterations are independent.
See [Extract Archive File](/steps/transform/archive-extract) for per-entry,
per-reader, and process-wide concurrent inflation limits.

Encrypted ZIP entries are rejected. Nested ZIP files stay `application/zip`
until you extract them and pass `{{ steps.extract.output }}` into another
list, extract, or [Search Files](/steps/ai/search-files) step. Git-backed
Agents do not run archive steps — they inspect sandbox files with filesystem
tools. Hosted vs headless vs on-prem ceilings: [Upload files](/guides/upload-files).

## Limits

| Limit                                 | Value                               |
| ------------------------------------- | ----------------------------------- |
| Archive format                        | ZIP only                            |
| Matching entries returned in one page | 10,000 (`limit` cannot exceed this) |
| Central-directory entries in the ZIP  | 10,000 including directories        |

Listing does not inflate file payloads. Extraction limits apply only when a
later step reads an entry.

## Configuration

Configuration goes inside the step's `with:` block.

<ParamField path="archive" type="string" required>
  Template expression or file reference for the ZIP archive to list. ZIP is the only accepted format in this version.
</ParamField>

<ParamField path="prefix" type="string">
  Optional folder prefix inside the archive after path normalization (for example invoices or invoices/).
</ParamField>

<ParamField path="search" type="string">
  Optional case-insensitive substring match on the normalized archive path.
</ParamField>

<ParamField path="offset" type="integer">
  Number of matching entries to skip after sorting. Default 0.
</ParamField>

<ParamField path="limit" type="integer">
  Maximum matching entries to return after sorting. Capped at 10000. Omit to return every matching entry up to that cap.
</ParamField>

## Output

<ResponseField path="entries" type="array<object>" required>
  Matching files, sorted by normalized path. Directories and junk paths are omitted.

  <Expandable title="entries properties">
    <ResponseField path="path" type="string" required>
      Normalized archive-relative path
    </ResponseField>

    <ResponseField path="compressedSize" type="integer" required>
      Declared compressed size in bytes
    </ResponseField>

    <ResponseField path="uncompressedSize" type="integer" required>
      Declared uncompressed size in bytes
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField path="total" type="integer" required>
  Number of matching entries before offset/limit pagination.
</ResponseField>