> ## 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 config: show, validate and locate the config file

> Reference for filetrace config: print every setting in effect, validate a configuration file before the agent reads it, and print which file is read.

`filetrace config` works with the configuration file: `show` prints every setting with the value in effect, `validate` checks a file and reports what is wrong with it, and `path` prints which file is read. It reads the file itself and does not need a running agent.

## Usage

```bash theme={null}
filetrace config show
filetrace config validate [<file>]
filetrace config path
```

## Which file is read

The file is `/etc/filetrace/config.toml`, or `$FILETRACE_CONFIG`, or the one named with the global option `--config`, which `config` also accepts after its action. The agent reads the file when it starts, and its own command-line options override it. The other commands take their default output format, `[output] format`, and the socket to reach the agent on, `[agent] socket`, from it.

If the default file, or the one `$FILETRACE_CONFIG` names, does not exist, the built-in defaults apply. A file named with `--config` must exist.

A setting that asks for something this build cannot do, such as `[storage] enabled = true`, is reported as a warning and ignored. An unknown setting or a value of the wrong kind is an error. [Configuration file reference](https://filetrace.mintlify.site/reference/configuration.md) describes every setting.

## show

`config show` prints every setting in the format of the configuration file, preceded by a comment that says where the values come from. Without a file, these are the defaults:

```bash theme={null}
filetrace config show
```

```toml theme={null}
# Built-in defaults; there is no configuration file at /etc/filetrace/config.toml.

[agent]
enabled = true
mode = "standard"
probes = "auto"
socket = "/run/filetrace/agent.sock"
ring_buffer_size = "4MB"
event_batch_size = 512
flush_interval = "250ms"
event_log_size = "1MB"
log_level = "info"

[network]
tcp = true
udp = true
ipv4 = true
ipv6 = true
# Not available in this build; true is ignored with a warning.
tc_egress = false
```

The output continues with the `[file]`, `[correlation]`, `[storage]`, `[limits]`, `[output]`, `[filters]`, `[prometheus]`, `[otlp]` and `[grpc]` sections. With a file, the first line names it:

```bash theme={null}
filetrace --config /etc/filetrace/config.toml config show
```

```toml theme={null}
# Settings in effect, read from /etc/filetrace/config.toml.

[agent]
enabled = true
mode = "standard"
probes = "auto"
socket = "/run/filetrace/agent.sock"
ring_buffer_size = "4MB"
event_batch_size = 512
flush_interval = "250ms"
event_log_size = "1MB"
log_level = "warn"
```

Because the output is a complete, valid configuration file, it is a way to write a first one:

```bash theme={null}
filetrace config show | sudo tee /etc/filetrace/config.toml >/dev/null
```

Warnings about settings this build ignores go to standard error, after the settings.

## validate

`config validate` checks a file without starting anything. Without a file argument, it checks the file that would be read.

```bash theme={null}
filetrace config validate /etc/filetrace/config.toml
```

```text theme={null}
/etc/filetrace/config.toml is valid.
```

A file with ignored settings is valid with warnings: the result line counts them, and each warning follows on standard error. Without a file at the default location, the command says that the built-in defaults apply.

An error names the file, the line, the section and the setting, and the command exits with 6. For a file that sets an unknown mode:

```toml theme={null}
[agent]
mode = "fast"
[storage]
enabled = true
```

```bash theme={null}
filetrace config validate /tmp/bad.toml
```

```text theme={null}
/tmp/bad.toml:2: [agent] mode: expected "minimal" or "standard"
```

Validate a file before you install it, so that the agent does not refuse to start: the agent also exits with 6 on an invalid file, and the systemd service does not retry a start that failed with that code.

## path

`config path` prints the path of the file that would be read, whether or not it exists:

```bash theme={null}
filetrace config path
```

## Options

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

The configuration file to show, validate or locate. Accepted before `config`, as a global option, or after the action. A file argument of `validate` overrides the global option.

## Examples

```bash theme={null}
filetrace config show > /etc/filetrace/config.toml
filetrace config validate ./config.toml
filetrace --config ./config.toml config show
```

## Exit codes

| Code | Meaning |
| - | - |
| 0 | The configuration is usable |
| 2 | Invalid arguments, such as a missing or unknown action |
| 6 | The configuration is not usable: the file cannot be read or holds an error |


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