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

# Flags reference

> Every Filetrace command-line option in one place: global options, output formats, selection filters, activity and sorting, command-specific flags, and which command accepts which.

Every option the `filetrace` command accepts, grouped by what it does, with the commands that take it. The [filters page](https://filetrace.mintlify.site/cli/filters.md) explains the value syntax in depth; this page is the index you can scan.

## How options are written

An option that takes a value accepts it as the next argument or after an equals sign, so `--since 1h` and `--since=1h` are the same. Options may come in any order after the command. Giving the same option twice keeps the last value.

```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
```

An option a command does not take is refused with exit code 2. If another command takes it, the message says so, as in `--protocol does not apply to 'top processes'`; otherwise it is reported as an unknown argument.

## Global options

These go before the command.

| Option | Value | Default | Meaning |
| - | - | - | - |
| `--socket` | path | `/run/filetrace/agent.sock` | Agent socket to connect to. Overrides `$FILETRACE_SOCKET` and the configuration file. |
| `--config` | path | `/etc/filetrace/config.toml` | Configuration file to read. A file named here must exist. |
| `-h`, `--help` | — | — | Print the overview, or a command's help after the command. |
| `--version` | — | — | Print version and build information. |

## Output options

| Option | Value | Commands | Meaning |
| - | - | - | - |
| `--format` | `table`, `json`, `jsonl`, `csv`, `quiet` | all listing commands | Output format. `quiet` prints one identifier per row. |
| `--json` | — | all listing commands | Short for `--format json`. |
| `--jsonl` | — | `events` and the listing commands | Short for `--format jsonl`: one JSON object per line. |
| `--output` | path | all listing commands, `inspect` | Write to a file instead of standard output. |
| `--raw` | — | `events` | Print the agent's raw records; a format of its own, so it cannot be combined with `--format`. |

The default format comes from `[output] format` in the configuration file, or `table`. Output that is not a terminal is never styled. See [output formats](https://filetrace.mintlify.site/cli/output-formats.md) for the fields of each format.

## Selection filters

Every filter narrows the result; a record must match all of them. The value syntax for times, sizes, addresses, wildcards and regular expressions is on the [filters page](https://filetrace.mintlify.site/cli/filters.md).

| Option | Value | Selects |
| - | - | - |
| `--pid` | number | One process. |
| `--process`, `--name` | name with `*` wildcards | Processes by kernel name. |
| `--script` | path, `module:<name>` or `pool:<name>`, with `*` wildcards | Processes by the script they run, or transfers by the script that sent them. |
| `--user` | name or numeric ID | Processes of one user. |
| `--cgroup` | numeric ID or cgroup directory | Processes in one cgroup. |
| `--namespace` | inode number | Processes in one network, PID or mount namespace. |
| `--path`, `--file` | path with `*` wildcards | One file. |
| `--path-regex` | POSIX extended regular expression | Files whose path matches. |
| `--min-size` | size such as `100MB` | Files at least this large. |
| `--remote` | IP address or CIDR | One remote address or network. |
| `--local` | IP address or CIDR | One local address or network. |
| `--port` | 1–65535 | One local or remote port. |
| `--protocol` | `tcp`, `udp`, `all` | One transport protocol. |
| `--family` | `ipv4`, `ipv6` | One address family. |
| `--state` | `connecting`, `established`, `listening`, `closed`, `active`, `idle` | Sockets in one state. |
| `--method` | `sendfile`, `read-write` | Transfers made one way. |
| `--confidence` | `exact`, `strong`, `inferred`, `unknown`, `all` | Transfers at one confidence level. |
| `--min-bytes` | size such as `1MB` | Records with at least this many bytes. |
| `--deleted` | — | Files that no longer have a directory entry. |
| `--include-unknown` | — | Also list sent bytes that no file accounts for. |
| `--type` | comma-separated event types | Events of these types. |
| `--since` | duration or RFC 3339 time | Records active at or after this time. |
| `--until` | duration or RFC 3339 time | Records that started at or before this time. |

## Activity

| Option | Commands | Selects |
| - | - | - |
| `--active` | `files`, `transfers`, `flows`, `connections` | Records still in progress, or with traffic in the last 5 seconds. |
| `--completed` | `files`, `transfers` | Records not updated in the last 5 seconds. |
| `--active-only` | `processes` | Running processes with at least one open connection. |
| `--include-children` | `processes` | Add each process's descendants to its totals. |

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

## Sorting and limits

`--sort` orders rows by one key. Numeric keys sort largest first, except `pid`, which sorts ascending; `process` and `file` sort by name ascending.

| Command | Keys | Default |
| - | - | - |
| `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 |

`--limit` takes a positive number and caps the rows. In `inspect` it caps every list in the report.

## Command-specific options

| Option | Value | Commands | Meaning |
| - | - | - | - |
| `--deleted` | — | `files`, `transfers` | Only files that no longer have a directory entry. |
| `--include-unknown` | — | `files`, `transfers` | Also list sent bytes with no associated file. `transfers` includes them by default. |
| `--type` | list | `events` | Event types to print, such as `file_transfer,event_loss`. |
| `--raw` | — | `events` | Raw records instead of the formatted table. |
| `--follow`, `-f` | — | `events` | Keep printing new events as they arrive. |
| `--watch` | — | `stats` | Repeat the report. |
| `--interval` | duration | `watch`, `stats` | Refresh interval; at least `100ms`. `watch` defaults to `1s`, `stats` to `1s`. |
| `--direction` | `inbound`, `outbound`, `both` | `watch`, `flows` | Which traffic ranks processes and connections, or orders flows. |
| `--group-by` | `process`, `remote`, `port`, `protocol` | `flows` | Merge flows by one key. |
| `--no-ui` | — | `watch` | Print a snapshot per interval instead of the dashboard. |
| `--probes` | `auto`, `trampoline`, `kprobe` | `doctor` | Probe set to check. |
| `--resolve-hostnames` | — | `watch`, `files`, `transfers`, `connections`, `flows`, `inspect` | Show remote addresses by host name where a reverse lookup finds one. |

## Which command takes which option

| Option | 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 | |
| `--script` | | 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 | | | | | | |
| `--include-unknown` | | yes | yes | | | | | | |
| `--active` | | yes | yes | | yes | yes | | | |
| `--completed` | | yes | yes | | | | | | |
| `--active-only` | | | | yes | | | | | |
| `--include-children` | | | | 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 |
| `--type` | | | | | | | | yes | |
| `--raw` | | | | | | | | yes | |
| `--follow` | | | | | | | | yes | |
| `--direction` | yes | | | | | yes | | | |
| `--group-by` | | | | | | yes | | | |
| `--no-ui` | yes | | | | | | | | |
| `--interval` | yes | | | | | | | | |

Notes:

* In `top`, `--protocol` applies to the `files`, `destinations` and `connections` subjects; `top processes`, the default, does not accept it.
* In `watch`, the process filters apply to every view; `--file` and `--confidence` to the files view, `--min-bytes` to the files and processes views, and `--remote` and `--protocol` to the files and network views.
* In `events`, `--path` matches only file events, the network filters match only events that concern a socket, and `--script` matches only process events and `file_transfer`.
* In `inspect`, the target itself (a path, PID, socket ID, flow ID or address) does the selecting; `--since` narrows the history.

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Files sent by nginx to one network in the last hour, largest first
sudo filetrace files --process nginx --remote 203.0.113.0/24 --since 1h --sort bytes

# Only exact sendfile transfers of files over 100 MB
sudo filetrace files --method sendfile --confidence exact --min-size 100MB

# Processes of one user, with their children, by outbound rate
sudo filetrace processes --user www-data --include-children --sort outbound

# Flows merged by remote address, inbound first
sudo filetrace flows --group-by remote --direction inbound --since 15m

# Live events of two types, as JSON lines
sudo filetrace events --type file_transfer,event_loss --follow --jsonl

# The ten largest destinations, as CSV
sudo filetrace top destinations --limit 10 --format csv
```

## Related pages

* [Filters](https://filetrace.mintlify.site/cli/filters.md) — value syntax, how filters combine, and time ranges.
* [Output formats](https://filetrace.mintlify.site/cli/output-formats.md) — `--format`, `--json`, `--jsonl`, `--output`.
* [Exit codes](https://filetrace.mintlify.site/reference/exit-codes.md) — what each code means.
* [Configuration reference](https://filetrace.mintlify.site/reference/configuration.md) — the settings behind the defaults.


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