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

​

Related pages

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