> ## 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 watch: live view of file transfers > Reference for filetrace watch: the live dashboard with its views and keys, the --no-ui snapshot mode, foreground collection, options and exit codes. `filetrace watch` shows what the machine is sending, live: the file transfers in progress with the process, the destination, the method and the current rate of each. On a terminal it draws a dashboard that refreshes every second and switches between files, processes and connections with single keys; otherwise it prints a snapshot per interval. When no agent is running, it collects in the foreground for as long as it runs. ## Usage ```bash theme={null} filetrace watch [options] ``` ## The dashboard ```bash theme={null} sudo filetrace watch ``` ```text theme={null} FILETRACE web-01 · Linux 6.8 LIVE 4 13 6.67 MB/s Transfers Processes Outbound ACTIVE FILE TRANSFERS PROCESS FILE DESTINATION METHOD RATE CONFIDENCE nginx 1245 /var/www/stream.bin 203.0.113.25 sendfile 6.67 MB/s EXACT nginx 1245 /var/www/video.mp4 198.51.100.10 sendfile 0 B/s EXACT python 892 /data/export/customers.csv 203.0.113.50 read-write 0 B/s INFERRED ● EXACT: 2 ● INFERRED: 1 LOST: 0 [F] Files [P] Processes [N] Network [Space] Pause [?] Help [Q] Quit ``` From top to bottom: * **The header** names the host, the system and its kernel version, and the state: `LIVE`, `PAUSED` while refreshing is paused, or `DEGRADED` when the collector has lost events recently. * **The counters** give the transfers in progress, the active processes and the outbound rate of the whole machine. With `--direction inbound` the inbound rate replaces the outbound one; with `--direction both` both are shown. * **The view**: file transfers, processes or connections, chosen with the keys below. * **The confidence line** counts the transfers in progress by confidence, and the events the collector has lost since it started. * **The key line** shows the keys, with the current view highlighted. A transfer is in progress if it was updated within the last 5 seconds. Rates are bytes per second over the last one to two seconds, counted where the local socket accepts or delivers the bytes. ### Views | View | Columns | | - | - | | Files: ACTIVE FILE TRANSFERS | PROCESS (name and PID), FILE, DESTINATION, METHOD, RATE, CONFIDENCE | | Processes: PROCESSES | PID, PROCESS, OUTBOUND, FILES, CONNECTIONS, SENT | | Network: CONNECTIONS | PID, PROCESS, PROTOCOL, LOCAL, REMOTE, OUTBOUND, INBOUND | In the files view, a path too long for the terminal is shortened at its start, with `...`, so that the file name stays visible. A `*` after a confidence level marks a transfer during which events were lost. The processes view ranks processes by the rate they send at; with `--direction inbound` it shows INBOUND and RECEIVED instead of OUTBOUND and SENT, and with `--direction both` it shows OUTBOUND, FILES, CONNECTIONS, INBOUND and TOTAL. The network view lists open connections. ### Keys | Key | Action | | - | - | | `f` | File transfers in progress | | `p` | Processes, by the rate they send at | | `n` | Network: open connections | | `space` | Pause or resume refreshing | | `?` | Show or hide the help screen, which also explains the columns | | `q` | Quit; Ctrl-C also quits | The keys work in upper case too, and `h` also toggles the help screen. ## Snapshots without the dashboard With `--no-ui`, or whenever standard output or standard input is not a terminal, `watch` prints a snapshot per interval instead of a dashboard, so you can log activity to a file: ```bash theme={null} sudo filetrace watch --no-ui > activity.log ``` Each snapshot starts with a line holding the local time, then shows the counters, the file transfers in progress and the processes, and ends with the confidence line. It has no network view and no key line, and each table holds 10 rows unless `--limit` says otherwise: ```bash theme={null} sudo filetrace watch --no-ui --limit 5 ``` ```text theme={null} --- 2026-11-11 20:07:58 --- FILETRACE web-01 · Linux 7.0 LIVE 4 13 4.18 MB/s Transfers Processes Outbound ACTIVE FILE TRANSFERS PROCESS FILE DESTINATION METHOD RATE CONFIDENCE file-server 1024 /srv/export/media/files/stream.bin 127.0.0.1 sendfile 4.18 MB/s EXACT file-server 1016 /srv/export/media/files/backup.tar.gz ::1 sendfile 0 B/s EXACT file-server 1018 /srv/export/media/files/customers.csv 127.0.0.1 read-write 0 B/s INFERRED file-server 1014 /srv/export/media/files/video.mp4 127.0.0.1 sendfile 0 B/s EXACT PROCESSES PID PROCESS OUTBOUND FILES CONNECTIONS SENT 1024 file-server 4.18 MB/s 1 2 8.34 MB 1014 file-server 0 B/s 1 0 47.7 MB 1018 file-server 0 B/s 1 0 11.4 MB 1016 file-server 0 B/s 1 0 7.63 MB 1020 file-server 0 B/s 0 0 195 KB ● EXACT: 3 ● INFERRED: 1 LOST: 0 ``` `[output] timestamps = false` in the configuration leaves out the time line. ## Without an agent When no agent is serving the socket, `watch` starts a collector in the foreground and says so on standard error: ```text theme={null} The Filetrace agent is not running; monitoring in the foreground for this session. Only activity from now on is shown. ``` The collector needs the same privileges as the agent, uses the `[agent]` settings of the configuration file, exports nothing and stops when `watch` ends. If the agent is running but its socket is not accessible to your user, `watch` reports `Permission denied` instead; run it with `sudo`. ## How the filters apply | Filter | Files view | Processes view | Network view | | - | - | - | - | | `--pid`, `--process`, `--user`, `--cgroup`, `--namespace` | yes | yes | yes | | `--path`, `--confidence`, `--sort` | yes | | | | `--remote`, `--protocol` | yes | | yes | | `--min-bytes` | yes | yes | | `--sort` orders the transfers and defaults to `rate`. ## Options **--interval** `string` (default: 1s) Refresh interval, such as `500ms` or `2s`. The shortest is 100 ms. **--direction** `string` (default: outbound) Traffic that ranks processes and connections: `outbound`, `inbound` or `both`. **--no-ui** `boolean` Print a snapshot per interval instead of a dashboard. This is the default when output is not a terminal. **--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//ns` shows. **--path** `string` Only this file. `*` matches any run of characters, `/` included. Alias: `--file`. **--remote** `string` Only this remote address or CIDR network. **--protocol** `string` (default: all) Only this protocol: `tcp`, `udp` or `all`. **--confidence** `string` `exact`, `strong`, `inferred`, `unknown` or `all`. **--min-bytes** `string` At least this many bytes, such as `1KB`, `100MB` or `1GB`. **--sort** `string` (default: rate) Order of the transfers: `bytes`, `rate`, `process` or `file`. **--resolve-hostnames** `boolean` Show the destinations of the files view by host name where a reverse DNS lookup finds one. A name appears on the refresh after its lookup finishes. The lookups tell the DNS resolver which addresses are being looked at. **--limit** `number` Rows per table. By default, as many as fit on the terminal, or 10 with `--no-ui`. [Filters](https://filetrace.mintlify.site/cli/filters.md) describes the value syntax. [Watch transfers live](https://filetrace.mintlify.site/guides/live-monitoring.md) shows how to use the view day to day. ## Examples ```bash theme={null} sudo filetrace watch sudo filetrace watch --remote 203.0.113.0/24 --confidence exact sudo filetrace watch --sort bytes --min-bytes 1MB --interval 2s sudo filetrace watch --no-ui > activity.log ``` ## Exit codes | Code | Meaning | | - | - | | 0 | Quit normally | | 1 | General error | | 2 | Invalid arguments | | 3 | Permission denied: the agent socket is not accessible, or the foreground collector lacks privileges | | 5 | Unsupported platform or capability | | 6 | The configuration file cannot be read or is invalid | | 9 | The collector had lost events by the time `watch` ended | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.