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

# filetrace files: list files sent over the network

> Reference for filetrace files: the columns it prints, how to read BYTES and CONFIDENCE, every option with its values, examples with real output, and exit codes.

`filetrace files` lists the files that processes have sent over the network, most recently active first: which process sent each file, to which address, how many bytes and by which method. Every row carries the confidence of the association between the file and the socket.

## Usage

```bash theme={null}
filetrace files [options]
```

## What it shows

```bash theme={null}
sudo filetrace files
```

```text theme={null}
FILE                                   PROCESS      DESTINATION    BYTES  METHOD      CONFIDENCE
/srv/export/media/files/stream.bin     file-server  127.0.0.1    15.5 MB  sendfile    EXACT
/srv/export/media/files/customers.csv  file-server  127.0.0.1    11.4 MB  read-write  INFERRED
/srv/export/media/files/backup.tar.gz  file-server  ::1          7.63 MB  sendfile    EXACT
/srv/export/media/files/video.mp4      file-server  127.0.0.1    47.7 MB  sendfile    EXACT

Observed since 2026-11-11 20:07:55. History is not kept across agent restarts.
```

Each row is one transfer record: one file sent by one process on one socket.

| Column | Meaning |
| - | - |
| FILE | The file's path, followed by `(deleted)` for a file that no longer has a directory entry. A file whose path is not known shows as `(device <n> inode <n>)`. |
| PROCESS | The name of the process that sent it |
| DESTINATION | The remote address of the socket, without the port |
| BYTES | What the socket accepted from this file |
| METHOD | `sendfile` or `read-write` |
| CONFIDENCE | `EXACT` or `INFERRED`; a `*` after it marks a transfer during which events were lost |

BYTES is neither the size of the file nor the bytes read from it. Machine-readable formats carry all three numbers, as `file.size`, `transfer.bytes_read` and `transfer.bytes_sent`. Byte counts are what the local socket accepted, not bytes on the wire or acknowledged by the remote end.

The confidence levels:

| Level | Meaning |
| - | - |
| EXACT | The kernel moved the file's data to the socket itself (`sendfile`). |
| INFERRED | A thread read the file and then sent on the socket. The payload cannot be proven to come only from this file. |
| UNKNOWN | Bytes sent with no file that could be associated with them. Listed only with `--include-unknown` or `--confidence unknown`, with FILE showing `unknown`. |

[File attribution and confidence](https://filetrace.mintlify.site/concepts/attribution.md) explains the evidence behind each level. To see the bytes no file accounts for, use [`transfers`](https://filetrace.mintlify.site/cli/transfers); to see everything about one file, use [`inspect file`](https://filetrace.mintlify.site/cli/inspect).

## Options

**--deleted** `boolean`

Only files that no longer have a directory entry.

**--include-unknown** `boolean`

Also list sent bytes with no associated file, as rows with FILE `unknown` and CONFIDENCE `UNKNOWN`.

**--pid** `number`

Only this process.

**--process** `string`

Only processes with this name. `*` matches any run of characters. Alias: `--name`.

**--user** `string`

Only processes of this user, by name or numeric ID.

**--cgroup** `string`

Only processes in this cgroup, by numeric ID or cgroup directory.

**--namespace** `number`

Only processes in this network, PID or mount namespace, given as the inode number that `ls -Li /proc/<pid>/ns` shows.

**--path** `string`

Only this file. `*` matches any run of characters, `/` included. Alias: `--file`.

**--path-regex** `string`

Only files whose path matches this POSIX extended regular expression.

**--min-size** `string`

Only files at least this large, such as `100MB`.

**--remote** `string`

Only this remote address or CIDR network.

**--local** `string`

Only this local address or CIDR network.

**--port** `number`

Only this local or remote port.

**--protocol** `string` (default: all)

Only this protocol: `tcp`, `udp` or `all`.

**--method** `string`

`sendfile` or `read-write`. `splice`, `mmap` and `io_uring` are accepted but not observed by this build; with them the command exits with 5 instead of printing an empty list.

**--confidence** `string`

`exact`, `strong`, `inferred`, `unknown` or `all`.

**--min-bytes** `string`

At least this many bytes sent, such as `1KB`, `100MB` or `1GB`.

**--active** `boolean`

Only records still in progress: updated within the last 5 seconds.

**--completed** `boolean`

Only records that are no longer in progress.

**--since** `string`

Only records active at or after this time: a duration such as `10m`, `1h` or `7d`, or an RFC 3339 timestamp.

**--until** `string`

Only records that started at or before this time.

**--sort** `string`

`bytes`, `time`, `pid`, `rate`, `duration`, `process` or `file`. Without it, the most recently active come first.

**--resolve-hostnames** `boolean`

Show remote addresses by host name where a reverse DNS lookup finds one. The lookups tell the DNS resolver which addresses are being looked at.

**--limit** `number`

Show at most this many rows.

**--format** `string` (default: table)

`table`, `json`, `jsonl`, `csv` or `quiet`. Quiet prints one file path per row.

**--json** `boolean`

Short for `--format json`.

**--jsonl** `boolean`

Short for `--format jsonl`.

**--output** `string`

Write to this file instead of standard output.

Byte counts cover a record's whole observed lifetime; `--since` and `--until` select which records are listed. [Filters](https://filetrace.mintlify.site/cli/filters.md) describes the value syntax, and [output formats](https://filetrace.mintlify.site/cli/output-formats.md) the formats.

## Examples

```bash theme={null}
filetrace files --active
filetrace files --path /data/report.csv
filetrace files --path '/data/*' --since 1h
filetrace files --confidence exact --min-bytes 100MB
filetrace files --jsonl
```

Files sent to a network with EXACT confidence:

```bash theme={null}
sudo filetrace files --remote 127.0.0.0/8 --confidence exact
```

```text theme={null}
FILE                                PROCESS      DESTINATION    BYTES  METHOD    CONFIDENCE
/srv/export/media/files/stream.bin  file-server  127.0.0.1    15.5 MB  sendfile  EXACT
/srv/export/media/files/video.mp4   file-server  127.0.0.1    47.7 MB  sendfile  EXACT

Observed since 2026-11-11 20:07:55. History is not kept across agent restarts.
```

The three largest transfers:

```bash theme={null}
sudo filetrace files --sort bytes --limit 3
```

```text theme={null}
FILE                                   PROCESS      DESTINATION    BYTES  METHOD      CONFIDENCE
/srv/export/media/files/video.mp4      file-server  127.0.0.1    47.7 MB  sendfile    EXACT
/srv/export/media/files/stream.bin     file-server  127.0.0.1    15.5 MB  sendfile    EXACT
/srv/export/media/files/customers.csv  file-server  127.0.0.1    11.4 MB  read-write  INFERRED
```

One file as JSON:

```bash theme={null}
sudo filetrace files --path /srv/export/media/files/video.mp4 --json
```

```json theme={null}
[
 {"event":"file_transfer","transfer_id":"tr_1","timestamp":"2026-11-11T20:07:56.063Z","host":"web-01","platform":"linux","process":{"pid":1014,"ppid":772,"name":"file-server","executable":"/usr/local/bin/file-server"},"file":{"path":"/srv/export/media/files/video.mp4","inode":626324,"device":63,"size":50000000,"owner":"root","filesystem":"overlay","deleted":false},"network":{"protocol":"tcp","socket_id":3,"local_ip":"127.0.0.1","local_port":43090,"remote_ip":"127.0.0.1","remote_port":34477},"transfer":{"method":"sendfile","bytes_sent":50000000,"bytes_per_second":0,"operations":1,"started":"2026-11-11T20:07:56.063Z","duration_ms":0,"state":"active","confidence":"exact","evidence":["direct_file_to_socket_transfer","file_identity","socket_identity","remote_endpoint"],"incomplete":false}}
]
```

[JSON output schema](https://filetrace.mintlify.site/reference/json-output.md) describes every field.

## Exit codes

| Code | Meaning |
| - | - |
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments, including an invalid `--path-regex` |
| 3 | Permission denied: the agent socket is not accessible to this user |
| 4 | No agent is running |
| 5 | Unsupported platform, or a `--method` this build does not observe |
| 6 | The configuration file cannot be read or is invalid |
| 9 | Partial results: events were lost in the queried time range |


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