> ## 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 command-line interface

> Synopsis, global options, environment variables, the command list, the privileges each command needs and how to get help for the filetrace command.

`filetrace` is the command-line interface to Filetrace. Most commands ask the running agent (`filetrace-agent`) over a local socket and print what it has observed; a few check the machine or the configuration without an agent. This page covers what all commands share: the synopsis, the global options and environment variables, the privileges they need and how to get help.

## Synopsis

```bash theme={null}
filetrace [--socket <path>] [--config <path>] <command> [options]
```

Global options go before the command. Every 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.

## Global options

**--socket** `string` (default: /run/filetrace/agent.sock)

Path of the agent socket to connect to. Without this option, the command uses `$FILETRACE_SOCKET`, then the `[agent] socket` setting of the configuration file, then the default. The macOS build, which has no collection, uses `/var/run/filetrace/agent.sock` as its default.

**--config** `string` (default: /etc/filetrace/config.toml)

Configuration file to read. The commands take their default output format and the agent socket from it. A file named with this option must exist; see [config](https://filetrace.mintlify.site/cli/config.md).

**-h, --help** `boolean`

Print the overview of commands and options. After a command, print that command's help.

**--version** `boolean`

Print version and build information, the same as [`filetrace version`](https://filetrace.mintlify.site/cli/version).

## Environment variables

| Variable | Effect |
| - | - |
| `FILETRACE_SOCKET` | Agent socket to connect to. `--socket` takes precedence over it, and it takes precedence over the configuration file. |
| `FILETRACE_CONFIG` | Configuration file to read instead of `/etc/filetrace/config.toml`. `--config` takes precedence over it. If the file does not exist, the built-in defaults apply. |
| `NO_COLOR` | Any non-empty value turns off colors and bold text. |
| `TERM` | The value `dumb` turns off colors and bold text. |

Output that does not go to a terminal is never styled.

## Running filetrace without a command

`filetrace` alone reports whether an agent is serving the socket and lists the commands. With an agent running, the status line names the backend, the probe set and the mode, followed by the number of active transfers and processes, the outbound rate and the share of events the agent received without loss:

```bash theme={null}
sudo filetrace
```

```text theme={null}
Filetrace - File-to-Network Observability

● RUNNING   Linux eBPF (trampolines), standard mode
  0 active transfers   0 processes   0 B/s outbound   100.0% of events delivered

Main commands:
  watch         Live monitoring
  files         File transfers
  processes     Process activity
  connections   Network connections
  flows         Network flow details
  inspect       Inspect a file, process, socket, flow or address
  events        Raw events
  stats         Agent statistics
  doctor        System diagnostics
  config        Show or validate the configuration
  version       Version and build information

More commands:
  top           Highest-volume processes, files or destinations
  transfers     Transfer records, with unattributed bytes
  capabilities  Supported features
  agent         Run or control the background agent
  help          Help for a command

See 'filetrace help' for the options, and 'filetrace help <command>' for a
command's own.
```

Without an agent, the status line says how to start collecting:

```text theme={null}
○ NOT RUNNING   'sudo filetrace watch' collects for as long as it runs;
                'sudo filetrace agent run' collects in the background
```

When an agent is running but its socket is not accessible to your user, the status line says `RUNNING` and asks you to use `sudo`. The command exits with 0 in every case.

## Commands

The help lists the commands in two groups. The main commands cover everyday work:

| Command | Shows |
| - | - |
| [`watch`](https://filetrace.mintlify.site/cli/watch) | Live view of the file transfers in progress, with process, destination, method and rate |
| [`files`](https://filetrace.mintlify.site/cli/files) | Files associated with network transfers |
| [`processes`](https://filetrace.mintlify.site/cli/processes) | Outbound rate, files sent and open connections per process |
| [`connections`](https://filetrace.mintlify.site/cli/connections) | Open and recently closed sockets, by their local and remote ends |
| [`flows`](https://filetrace.mintlify.site/cli/flows) | Bytes per process, socket and remote endpoint |
| [`inspect`](https://filetrace.mintlify.site/cli/inspect) | Everything known about one file, process, socket, flow or address |
| [`events`](https://filetrace.mintlify.site/cli/events) | The agent's records in the order they were made |
| [`stats`](https://filetrace.mintlify.site/cli/stats) | The agent's own events, losses, CPU, memory and table usage |
| [`doctor`](https://filetrace.mintlify.site/cli/doctor) | Whether this machine can be monitored: kernel, every probe, features, pipeline |
| [`config`](https://filetrace.mintlify.site/cli/config) | The configuration in effect; validates a file |
| [`version`](https://filetrace.mintlify.site/cli/version) | Version, build and platform |

More commands:

| Command | Shows |
| - | - |
| [`top`](https://filetrace.mintlify.site/cli/top) | Highest-volume processes, files, destinations or connections |
| [`transfers`](https://filetrace.mintlify.site/cli/transfers) | Transfer records, including sent bytes that no file accounts for |
| [`capabilities`](https://filetrace.mintlify.site/cli/capabilities) | Each feature as FULL, PARTIAL, UNAVAILABLE or DISABLED, with the reason |
| [`agent`](https://filetrace.mintlify.site/cli/agent) | Run the agent in the foreground, report its status or stop it |
| `help` | The overview, or the help of one command |

The agent itself is a separate program, [`filetrace-agent`](https://filetrace.mintlify.site/cli/filetrace-agent).

## Privileges

Only the agent needs the privileges to load BPF programs. The agent creates its socket so that only its owner can open it, and accepts connections only from root and from the user it runs as. When the agent runs as root, as the packaged service does, every command that queries it needs `sudo`:

```bash theme={null}
sudo filetrace files
```

A command that cannot open the socket reports `Permission denied` and exits with 3.

When no agent is serving the socket, the query commands exit with 4 and say how to start one:

```bash theme={null}
filetrace --socket /run/filetrace/agent.sock files
```

```text theme={null}
The Filetrace agent is not running (/run/filetrace/agent.sock: No such file or directory).

Start it with:
  sudo filetrace agent run

To check what this machine supports:
  sudo filetrace doctor
```

Two commands collect on their own instead: [`watch`](https://filetrace.mintlify.site/cli/watch) and [`events --follow`](https://filetrace.mintlify.site/cli/events) start a collector in the foreground for as long as they run when no agent is running. Such a collector needs the same privileges as the agent, uses the `[agent]` settings of the configuration file, shows only activity from the moment it starts and exports nothing.

Some commands do not need an agent at all:

| Command | Without an agent |
| - | - |
| [`doctor`](https://filetrace.mintlify.site/cli/doctor) | Checks the machine directly; loading the probes needs root, or `CAP_BPF` with `CAP_PERFMON` |
| [`capabilities`](https://filetrace.mintlify.site/cli/capabilities) | Checks the machine directly, with the same privileges as the agent |
| [`config`](https://filetrace.mintlify.site/cli/config) | Reads the configuration file only |
| [`version`](https://filetrace.mintlify.site/cli/version) | Reports `Not running` for the agent |

The command and the agent speak one protocol version. If they differ, the command reports that the agent speaks a different protocol version; upgrade `filetrace` and `filetrace-agent` together.

## Getting help

`filetrace help` prints the overview of commands and global options. `filetrace help <command>` prints a command's usage, options, examples and exit codes:

```bash theme={null}
filetrace help files
```

`-h` or `--help` anywhere among a command's arguments does the same, so `filetrace files --since 1h --help` prints the help of `files`. The exception is `filetrace agent run --help`, which prints the help of the agent itself.

## Exit codes

The commands share one set of exit codes:

| Code | Meaning |
| - | - |
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Permission denied |
| 4 | Agent unavailable |
| 5 | Unsupported platform or capability |
| 6 | The configuration file cannot be read or is invalid |
| 9 | Partial results: events were lost in the queried time range |

With code 9 the output is still printed; a warning on standard error gives the number of lost events and the affected time window, so standard output stays parseable. [doctor](https://filetrace.mintlify.site/cli/doctor.md), [config](https://filetrace.mintlify.site/cli/config.md) and [agent status](https://filetrace.mintlify.site/cli/agent.md) give some codes a meaning of their own. [Exit codes](https://filetrace.mintlify.site/reference/exit-codes.md) lists them all.

## Command reference

> [card] [watch](https://filetrace.mintlify.site/cli/watch.md)
>
> Live view of the transfers in progress.

> [card] [files](https://filetrace.mintlify.site/cli/files.md)
>
> Files associated with network transfers.

> [card] [transfers](https://filetrace.mintlify.site/cli/transfers.md)
>
> Transfer records, with unattributed bytes.

> [card] [processes](https://filetrace.mintlify.site/cli/processes.md)
>
> Network activity per process.

> [card] [connections](https://filetrace.mintlify.site/cli/connections.md)
>
> Open and recently closed sockets.

> [card] [flows](https://filetrace.mintlify.site/cli/flows.md)
>
> Bytes per process, socket and remote endpoint.

> [card] [top](https://filetrace.mintlify.site/cli/top.md)
>
> Highest-volume processes, files, destinations or connections.

> [card] [events](https://filetrace.mintlify.site/cli/events.md)
>
> The agent's records in order, past or live.

> [card] [inspect](https://filetrace.mintlify.site/cli/inspect.md)
>
> One file, process, socket, flow or address from every side.

> [card] [agent](https://filetrace.mintlify.site/cli/agent.md)
>
> Run the agent, report its status or stop it.

> [card] [filetrace-agent](https://filetrace.mintlify.site/cli/filetrace-agent.md)
>
> The agent program and its options.

> [card] [stats](https://filetrace.mintlify.site/cli/stats.md)
>
> The agent's own events, losses and resources.

> [card] [doctor](https://filetrace.mintlify.site/cli/doctor.md)
>
> Whether and how well this machine can be monitored.

> [card] [capabilities](https://filetrace.mintlify.site/cli/capabilities.md)
>
> Each feature and its status, with the reason.

> [card] [config](https://filetrace.mintlify.site/cli/config.md)
>
> Show, validate or locate the configuration file.

> [card] [version](https://filetrace.mintlify.site/cli/version.md)
>
> Version, build and platform information.

[Filters](https://filetrace.mintlify.site/cli/filters.md) and [output formats](https://filetrace.mintlify.site/cli/output-formats.md) describe the options that the listing commands share.


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