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

# Filter options of the listing commands

> The filter options that the listing commands share: value syntax for times, sizes, addresses, wildcards and regular expressions, and which command takes which.

The listing commands (`watch`, `files`, `transfers`, `processes`, `connections`, `flows`, `top`, `events` and `inspect`) share one set of filter options. This page describes the syntax of each value, how filters combine, how `--since` and `--until` select records, and which command accepts which filter.

## How filters combine

Every filter you give narrows the result: a record is listed only if it matches all of them. Giving the same option twice keeps the last value. `--path` and `--path-regex` set the same pattern, so the one given last applies.

Each command accepts only the filters that apply to what it lists, and refuses any other option with exit code 2. An option that another command takes is named as not applying, as in `--protocol does not apply to 'top processes'`; anything else is reported as an unknown argument.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sudo filetrace files --process nginx --remote 203.0.113.0/24 --since 1h --min-bytes 100MB
```

## Value syntax

### Times

`--since` and `--until` take either a duration back from now or an RFC 3339 timestamp.

| Form | Examples | Notes |
| - | - | - |
| Duration | `500ms`, `30s`, `10m`, `1h`, `7d`, `1.5h` | A number with one of the units `ms`, `s`, `m`, `h`, `d`. The unit is required. |
| RFC 3339 timestamp | `2026-11-11T20:00:00Z`, `2026-11-11T21:00:00.250+01:00` | A time zone, `Z` or an offset, is required. A space may replace the `T` if you quote the value. |

History starts when the agent starts, so a time before that selects everything the agent has.

### Sizes

`--min-bytes` and `--min-size` take a number with an optional unit: `B`, `K` or `KB`, `M` or `MB`, `G` or `GB`, `T` or `TB`, in upper or lower case. Units are powers of 1024, so `1KB` is 1024 bytes and `100MB` is 104857600 bytes. A number without a unit counts bytes, and a fraction such as `1.5GB` is accepted.

### Addresses and ports

`--remote` and `--local` take an IPv4 or IPv6 address, or a network in CIDR notation:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sudo filetrace files --remote 203.0.113.42
sudo filetrace files --remote 203.0.113.0/24
sudo filetrace connections --local 2001:db8::/32
```

An address without a prefix length matches that address only. An IPv4 network never matches an IPv6 endpoint, and the other way round.

`--port` takes a number from 1 to 65535 and matches records whose local or remote port is that number.

### Process names

`--process`, and its alias `--name`, match the process name shown in the PROCESS column: the kernel's command name, which holds at most 15 characters. A `*` matches any run of characters; without one, the name must match exactly, including case.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sudo filetrace processes --process 'python*'
```

### Paths

`--path`, and its alias `--file`, match the whole path of a file. A `*` matches any run of characters, `/` included, so `/data/*` also matches files in the subdirectories of `/data`. Without a `*`, the path must match exactly. Quote patterns so that the shell does not expand them:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sudo filetrace files --path '/data/*' --since 1h
sudo filetrace files --path '*.csv'
```

### Regular expressions

`--path-regex` takes a POSIX extended regular expression. It matches if it occurs anywhere in the path; anchor it with `^` and `$` to match the whole path. An invalid expression is reported and the command exits with 2.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sudo filetrace files --path-regex '^/srv/(exports|backups)/.*\.tar\.gz$'
```

### Users, cgroups and namespaces

| Option | Value |
| - | - |
| `--user` | A user name or a numeric user ID |
| `--cgroup` | A numeric cgroup ID, or a directory of the cgroup tree, whose inode number is its ID |
| `--namespace` | The inode number of a network, PID or mount namespace, as `ls -Li /proc/<pid>/ns` shows it |

These filters select processes, and the sockets, flows and transfers of those processes. Machine-readable output of `processes` carries the matching values as `cgroup_id`, `pid_namespace`, `mount_namespace` and `network_namespace`.

### Keywords

| Option | Values |
| - | - |
| `--protocol` | `tcp`, `udp` or `all` (default `all`) |
| `--family` | `ipv4` or `ipv6`; matches when either end of the socket has that family |
| `--confidence` | `exact`, `strong`, `inferred`, `unknown` or `all`. `unknown` lists sent bytes that no file accounts for. No probe produces `strong`. |
| `--method` | `sendfile` or `read-write`. `splice`, `mmap` and `io_uring` are accepted, but this build does not observe them: the command says so and exits with 5 instead of printing an empty list. |
| `--state` | `connecting`, `established`, `listening`, `closed` for TCP sockets; `active` and `idle` for UDP sockets, which turn idle after 30 seconds without traffic |

See [file attribution and confidence](https://filetrace.mintlify.site/concepts/attribution.md) for what the confidence levels and methods rest on.

## Time ranges and activity

`--since` selects records that were active at or after the given time; `--until` selects records that started at or before it. Together they select the records whose observed lifetime overlaps the range.

> [!NOTE]
>
> `--since` and `--until` choose which records are listed, not which bytes are counted. Byte counts always cover a record's whole observed lifetime. A transfer that started two hours ago and is still running shows all of its bytes with `--since 10m`.

In [`events`](https://filetrace.mintlify.site/cli/events), every record is one point in time, and the range selects the events made within it.

If the agent lost events within the queried range, the command still prints its result, warns on standard error and exits with 9.

The activity options refer to the last few seconds:

| Option | Commands | Selects |
| - | - | - |
| `--active` | `files`, `transfers` | Transfers updated within the last 5 seconds |
| `--completed` | `files`, `transfers` | Transfers not updated within the last 5 seconds |
| `--active` | `flows` | Flows with traffic within the last 5 seconds |
| `--active` | `connections` | Sockets that are open: not closed and not idle |
| `--active-only` | `processes` | Running processes with at least one open connection |

`--active` and `--completed` together select everything.

## Which commands take which filters

| Filter | watch | files | transfers | processes | connections | flows | top | events | inspect |
| - | - | - | - | - | - | - | - | - | - |
| `--pid` | yes | yes | yes | yes | yes | yes | yes | yes | |
| `--process`, `--name` | yes | yes | yes | yes | yes | yes | yes | yes | |
| `--user` | yes | yes | yes | yes | yes | yes | | | |
| `--cgroup` | yes | yes | yes | yes | yes | yes | | | |
| `--namespace` | yes | yes | yes | yes | yes | yes | | | |
| `--path`, `--file` | yes | yes | yes | | | | | yes | |
| `--path-regex` | | yes | yes | | | | | | |
| `--min-size` | | yes | yes | | | | | | |
| `--remote` | yes | yes | yes | | yes | yes | | yes | |
| `--local` | | yes | yes | | yes | yes | | yes | |
| `--port` | | yes | yes | | yes | yes | | yes | |
| `--protocol` | yes | yes | yes | | yes | yes | yes | yes | |
| `--family` | | | | | yes | yes | | yes | |
| `--state` | | | | | yes | | | | |
| `--method` | | yes | yes | | | | | | |
| `--confidence` | yes | yes | yes | | | | | | |
| `--min-bytes` | yes | yes | yes | | | yes | | | |
| `--deleted` | | yes | yes | | | | | | |
| `--active` | | yes | yes | | yes | yes | | | |
| `--completed` | | yes | yes | | | | | | |
| `--since` | | yes | yes | yes | yes | yes | yes | yes | yes |
| `--until` | | yes | yes | yes | yes | yes | yes | yes | |
| `--sort` | yes | yes | yes | yes | yes | yes | | | |
| `--limit` | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| `--resolve-hostnames` | yes | yes | yes | | yes | yes | | | yes |

Notes on the table:

* In `top`, `--protocol` applies to the `files`, `destinations` and `connections` subjects; `top processes`, the default, does not accept it.
* In `watch`, the process filters (`--pid`, `--process`, `--user`, `--cgroup`, `--namespace`) apply to every view; [watch](https://filetrace.mintlify.site/cli/watch.md) lists which view each of the others applies to.
* In `events`, `--path` matches only file events (`file_seen` and `file_transfer`), and the network filters match only events that concern a socket.
* In `inspect`, the target itself (a path, PID, socket ID, flow ID or address) does the selecting; `--since` narrows the history.

## Sorting and limits

`--sort` orders the rows by one key. The keys each command accepts:

| Command | Keys | Default order |
| - | - | - |
| `files`, `transfers` | `bytes`, `time`, `pid`, `rate`, `duration`, `process`, `file` | Most recently active first |
| `processes` | `outbound`, `inbound`, `connections`, `bytes`, `time`, `pid`, `process` | Outbound rate, then bytes sent |
| `connections` | `outbound`, `inbound`, `bytes`, `time`, `pid`, `rate`, `duration`, `process` | Most recently active first |
| `flows` | `outbound`, `inbound`, `bytes`, `time`, `pid`, `rate`, `duration`, `process` | Bytes sent, largest first |
| `watch` | `bytes`, `rate`, `process`, `file` | Current rate |

Numeric keys sort largest first, except `pid`, which sorts in ascending order. `process` and `file` sort by name or path in ascending order. `bytes` is the bytes sent for transfers and the bytes sent and received together for processes, connections and flows.

`--limit` takes a positive number and caps the rows; in `inspect` it caps every list in the report. See each command's page for its default.

## Related pages

* [Output formats](https://filetrace.mintlify.site/cli/output-formats.md) describes `--format`, `--json`, `--jsonl` and `--output`.
* [Records and identifiers](https://filetrace.mintlify.site/concepts/data-model.md) explains what a process, socket, flow and transfer record is.


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