Flags reference

Every option the filetrace command accepts, grouped by what it does, with the commands that take it. The filters page 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.

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

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

# 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

Filters — value syntax, how filters combine, and time ranges.
Output formats — --format, --json, --jsonl, --output.
Exit codes — what each code means.
Configuration reference — the settings behind the defaults.

Using the CLI

Monitoring commands

Agent and system

How options are written

Global options

Output options

Selection filters

Activity

Sorting and limits

Command-specific options

Which command takes which option

Examples

​How options are written

​Global options

​Output options

​Selection filters

​Activity

​Sorting and limits

​Command-specific options

​Which command takes which option

​Examples

​Related pages

How options are written

Global options

Output options

Selection filters

Activity

Sorting and limits

Command-specific options

Which command takes which option

Examples

Related pages