# ftp\_list

Lists files and directories at a specified path on the FTP/SFTP server. Must be used inside an `ftp_session` block.

```liquid
{% ftp_session host: "ftp.example.com", user: "myuser", password: "mypass" %}
  {% ftp_list path: "/data" as result %}

  {% if result.ok %}
    {% for file in result.files %}
      {% log file.name %}
    {% endfor %}
  {% endif %}
{% endftp_session %}
```

#### Syntax

```liquid
{% ftp_list path: "/directory/path" as result_variable %}
```

#### Parameters

| Parameter | Required | Description                                    |
| --------- | -------- | ---------------------------------------------- |
| `path`    | Yes      | Directory path to list                         |
| `pattern` | No       | Glob pattern to filter files (e.g., `"*.csv"`) |

#### Result Object

| Property | Type        | Description                                         |
| -------- | ----------- | --------------------------------------------------- |
| `ok`     | boolean     | `true` if listing succeeded                         |
| `error`  | string/null | Error message if `ok` is `false`, `null` on success |
| `files`  | array       | Array of file objects                               |

Example result:

```json
{
  "ok": true,
  "error": null,
  "files": [
    {
      "name": "data.csv",
      "type": "file",
      "size": 1024,
      "path": "/exports/data.csv",
      "modifiedAt": 1704067200
    }
  ]
}
```

#### File Object Properties

| Property     | Type   | Description                         |
| ------------ | ------ | ----------------------------------- |
| `name`       | string | File or directory name              |
| `path`       | string | Full path to the file               |
| `type`       | string | `"file"` or `"dir"`                 |
| `size`       | number | File size in bytes                  |
| `modifiedAt` | number | Unix timestamp of last modification |

#### Examples

**List all files:**

```liquid
{% ftp_session host: FTP_HOST, user: FTP_USER, password: FTP_PASSWORD %}
  {% ftp_list path: "/exports" as result %}

  {% if result.ok %}
    {% log "Found files:" %}
    {% for file in result.files %}
      {% log file.name %}
    {% endfor %}
  {% else %}
    {% log result.error %}
  {% endif %}
{% endftp_session %}
```

**Filter by pattern:**

```liquid
{% ftp_session host: FTP_HOST, user: FTP_USER, password: FTP_PASSWORD %}
  {% ftp_list path: "/data", pattern: "*.csv" as csv_files %}

  {% for file in csv_files.files %}
    {% log file.name %}
  {% endfor %}
{% endftp_session %}
```

**Filter files only (exclude directories):**

```liquid
{% ftp_session host: FTP_HOST, user: FTP_USER, password: FTP_PASSWORD %}
  {% ftp_list path: "/uploads" as result %}

  {% for item in result.files %}
    {% if item.type == "file" %}
      {% log item.name %}
    {% endif %}
  {% endfor %}
{% endftp_session %}
```

**Sort by modification date:**

```liquid
{% ftp_session host: FTP_HOST, user: FTP_USER, password: FTP_PASSWORD %}
  {% ftp_list path: "/logs" as result %}

  {% assign sorted_files = result.files | sort: "modifiedAt" | reverse %}
  {% assign latest_file = sorted_files | first %}
  {% log latest_file.name %}
{% endftp_session %}
```

#### Notes

* Must be used inside an `ftp_session` block
* Consumes 2 credits per operation
* Pattern uses glob syntax (e.g., `*.csv`, `report_*.txt`, `**/*.json`)
* Returns empty `files` array if directory is empty