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

# Output formats: table, JSON, JSON Lines, CSV and quiet

> How the commands print tables, JSON, JSON Lines, CSV and bare IDs, what --output does, and how exact values differ between human and machine formats.

Every listing command prints a table by default and can print the same records as JSON, JSON Lines, CSV or a bare list of IDs for scripts. This page describes each format, the shortcuts and the `--output` option, the configured default, and the notes that tables add below the rows.

## Choosing a format

`--format` selects the format. `--json` and `--jsonl` are short for `--format json` and `--format jsonl`. Not every command prints every format:

| Command | Formats | `--output` |
| - | - | - |
| [`files`](https://filetrace.mintlify.site/cli/files), [`transfers`](https://filetrace.mintlify.site/cli/transfers), [`processes`](https://filetrace.mintlify.site/cli/processes), [`connections`](https://filetrace.mintlify.site/cli/connections), [`flows`](https://filetrace.mintlify.site/cli/flows), [`top`](https://filetrace.mintlify.site/cli/top) | `table`, `json`, `jsonl`, `csv`, `quiet` | yes |
| [`events`](https://filetrace.mintlify.site/cli/events) | `table`, `json`, `jsonl`, and `--raw` | yes |
| [`inspect`](https://filetrace.mintlify.site/cli/inspect) | `table`, `json` | yes |
| [`stats`](https://filetrace.mintlify.site/cli/stats), [`doctor`](https://filetrace.mintlify.site/cli/doctor), [`capabilities`](https://filetrace.mintlify.site/cli/capabilities) | `table`, `json` | no |
| [`watch`](https://filetrace.mintlify.site/cli/watch) | a dashboard, or snapshots with `--no-ui` | no |

A format that a command cannot print is an invalid argument: the command names the formats it accepts and exits with 2.

## Table

Tables are for reading. Byte counts and rates are rounded to three significant digits in units of 1024 (`KB`, `MB`, `GB`), times are local, protocols and states are in upper case, and a value that is not known shows as `-`.

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

```text theme={null}
FILE                                   PROCESS      DESTINATION    BYTES  METHOD      CONFIDENCE
/srv/export/media/files/stream.bin     file-server  127.0.0.1    15.5 MB  sendfile    EXACT
/srv/export/media/files/customers.csv  file-server  127.0.0.1    11.4 MB  read-write  INFERRED
/srv/export/media/files/backup.tar.gz  file-server  ::1          7.63 MB  sendfile    EXACT
/srv/export/media/files/video.mp4      file-server  127.0.0.1    47.7 MB  sendfile    EXACT

Observed since 2026-11-11 20:07:55. History is not kept across agent restarts.
```

### The footer

Below the rows of `files`, `transfers`, `processes`, `connections`, `flows` and `top`, a line says from when the agent has been observing: `Observed since <time>. History is not kept across agent restarts.` When nothing matched, it says `No <records> observed since <time>.` instead, so an empty answer is never mistaken for a complete one. History is kept in memory and starts when the agent starts.

[`events`](https://filetrace.mintlify.site/cli/events) ends with the number of events and how far back its event log reaches, and [`inspect`](https://filetrace.mintlify.site/cli/inspect) ends with the time its history starts. Machine-readable formats print no footer; `inspect --json` carries the same time as `observed_since`.

### The confidence marker

A `*` after a confidence level, as in `EXACT*`, marks a transfer during which the agent lost events, so its byte count may be low. The table then ends with this note:

```text theme={null}
* Events were lost while this transfer was in progress; its byte count may be low.
```

In machine-readable formats the same transfer has `"incomplete": true`.

### Colors

On a terminal, headers are bold and footers dim. Output to a pipe or a file, `--output`, a non-empty `NO_COLOR` and `TERM=dumb` all turn styling off.

## JSON

`--json` prints one array; each record is an object on a line of its own:

```bash theme={null}
sudo filetrace files --path /srv/export/media/files/video.mp4 --json
```

```json theme={null}
[
 {"event":"file_transfer","transfer_id":"tr_1","timestamp":"2026-11-11T20:07:56.063Z","host":"web-01","platform":"linux","process":{"pid":1014,"ppid":772,"name":"file-server","executable":"/usr/local/bin/file-server"},"file":{"path":"/srv/export/media/files/video.mp4","inode":626324,"device":63,"size":50000000,"owner":"root","filesystem":"overlay","deleted":false},"network":{"protocol":"tcp","socket_id":3,"local_ip":"127.0.0.1","local_port":43090,"remote_ip":"127.0.0.1","remote_port":34477},"transfer":{"method":"sendfile","bytes_sent":50000000,"bytes_per_second":0,"operations":1,"started":"2026-11-11T20:07:56.063Z","duration_ms":0,"state":"active","confidence":"exact","evidence":["direct_file_to_socket_transfer","file_identity","socket_identity","remote_endpoint"],"incomplete":false}}
]
```

A field whose value is not known is left out rather than set to `null` or zero. For example, `transfer.bytes_read` appears only for `read-write` transfers, the `file` object is absent for sent bytes that no file accounts for, and `remote_host` appears only with `--resolve-hostnames`. A transfer has the same fields whether it comes from `files`, `transfers` or `inspect`. [JSON output schema](https://filetrace.mintlify.site/reference/json-output.md) lists every field of every command.

## JSON Lines

`--jsonl` prints one object per line with no enclosing array, which suits streaming and line-oriented tools:

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

```json theme={null}
{"event":"file_transfer","transfer_id":"tr_3","timestamp":"2026-11-11T20:07:59.514Z","host":"web-01","platform":"linux","process":{"pid":1024,"ppid":772,"name":"file-server","executable":"/usr/local/bin/file-server"},"file":{"path":"/srv/export/media/files/stream.bin","inode":626330,"device":63,"size":40000000,"owner":"root","filesystem":"overlay","deleted":false},"network":{"protocol":"tcp","socket_id":16,"local_ip":"127.0.0.1","local_port":41814,"remote_ip":"127.0.0.1","remote_port":51871},"transfer":{"method":"sendfile","bytes_sent":16250000,"bytes_per_second":4273270,"operations":65,"started":"2026-11-11T20:07:56.193Z","duration_ms":3320,"state":"active","confidence":"exact","evidence":["direct_file_to_socket_transfer","file_identity","socket_identity","remote_endpoint"],"incomplete":false}}
{"event":"file_transfer","transfer_id":"tr_2","timestamp":"2026-11-11T20:07:56.072Z","host":"web-01","platform":"linux","process":{"pid":1018,"ppid":772,"name":"file-server","executable":"/usr/local/bin/file-server"},"file":{"path":"/srv/export/media/files/customers.csv","inode":626326,"device":63,"size":12000000,"owner":"root","filesystem":"overlay","deleted":false},"network":{"protocol":"tcp","socket_id":9,"local_ip":"127.0.0.1","local_port":60088,"remote_ip":"127.0.0.1","remote_port":52535},"transfer":{"method":"read-write","bytes_sent":12000000,"bytes_read":12000000,"bytes_per_second":0,"operations":184,"started":"2026-11-11T20:07:56.070Z","duration_ms":1,"state":"active","confidence":"inferred","evidence":["file_identity","socket_identity","remote_endpoint","thread_read_then_send","repeated_read_then_send","byte_balance"],"incomplete":false}}
```

## CSV

`--format csv` prints a header row with the field names, then one row per record. Nested fields are named with a dot (`process.pid`, `transfer.bytes_sent`), a field that is not known is empty, lists such as `transfer.evidence` are joined with `;`, and booleans are `true` or `false`. A value that contains a comma, a quote or a line break is quoted.

```bash theme={null}
sudo filetrace files --format csv
```

```text theme={null}
event,transfer_id,timestamp,host,platform,process.pid,process.ppid,process.name,process.executable,file.path,file.inode,file.device,file.size,file.owner,file.filesystem,file.deleted,network.protocol,network.socket_id,network.local_ip,network.local_port,network.remote_ip,network.remote_port,network.remote_host,transfer.method,transfer.bytes_sent,transfer.bytes_read,transfer.bytes_per_second,transfer.operations,transfer.started,transfer.duration_ms,transfer.state,transfer.confidence,transfer.evidence,transfer.incomplete
file_transfer,tr_3,2026-11-11T20:07:59.514Z,web-01,linux,1024,772,file-server,/usr/local/bin/file-server,/srv/export/media/files/stream.bin,626330,63,40000000,root,overlay,false,tcp,16,127.0.0.1,41814,127.0.0.1,51871,,sendfile,16250000,,4267188,65,2026-11-11T20:07:56.193Z,3320,active,exact,direct_file_to_socket_transfer;file_identity;socket_identity;remote_endpoint,false
file_transfer,tr_2,2026-11-11T20:07:56.072Z,web-01,linux,1018,772,file-server,/usr/local/bin/file-server,/srv/export/media/files/customers.csv,626326,63,12000000,root,overlay,false,tcp,9,127.0.0.1,60088,127.0.0.1,52535,,read-write,12000000,12000000,0,184,2026-11-11T20:07:56.070Z,1,active,inferred,file_identity;socket_identity;remote_endpoint;thread_read_then_send;repeated_read_then_send;byte_balance,false
```

The columns are always the same for a command, so every row of a file has the same shape.

## Quiet

`--format quiet` prints one identifier per row and nothing else, for use in shell pipelines:

| Command | Prints |
| - | - |
| `files` | The file path; rows without a known path are skipped |
| `transfers` | The transfer ID, such as `tr_3` |
| `processes` | The process ID |
| `connections` | The socket ID |
| `flows` | The flow ID |
| `top processes` | The process ID |
| `top files` | The file path |
| `top destinations` | The remote address |
| `top connections` | The flow ID |

```bash theme={null}
sudo filetrace files --format quiet
```

```text theme={null}
/srv/export/media/files/stream.bin
/srv/export/media/files/customers.csv
/srv/export/media/files/backup.tar.gz
/srv/export/media/files/video.mp4
```

Socket and flow IDs are what [`inspect`](https://filetrace.mintlify.site/cli/inspect) takes, so a quiet listing can feed it:

```bash theme={null}
sudo filetrace inspect socket "$(sudo filetrace connections --format quiet --limit 1)"
```

## Exact values in machine formats

JSON, JSON Lines, CSV and quiet output carry exact values: byte counts and rates are whole numbers of bytes and bytes per second, durations are milliseconds, and timestamps are RFC 3339 in UTC with milliseconds. The transfer that a table shows as `47.7 MB` has `"bytes_sent":50000000` in JSON, and its start time is `"started":"2026-11-11T20:07:56.063Z"`.

Byte counts are what the local socket accepted, not bytes on the wire or bytes the remote end acknowledged.

## Writing to a file

`--output <file>` writes the result to a file instead of standard output. The file is created, or truncated if it exists. Warnings and errors still go to standard error.

```bash theme={null}
sudo filetrace files --since 1h --format csv --output files.csv
```

Output written with `--output` is never styled, and `top` leaves out its heading line. For `stats`, `doctor` and `capabilities`, which have no `--output`, redirect standard output instead.

## The configured default

The `[output] format` setting of the [configuration file](https://filetrace.mintlify.site/reference/configuration.md) sets the default format:

```toml theme={null}
[output]
format = "jsonl"
timestamps = true
```

A command uses the configured format when it can print it and a table otherwise. With `format = "jsonl"`, `files` prints JSON Lines and `inspect` prints a table; with `format = "json"`, `inspect`, `stats`, `doctor` and `capabilities` print JSON too. An option on the command line always wins.

`timestamps = false` leaves the time out of each event in the table format of [`events`](https://filetrace.mintlify.site/cli/events), and out of the separator line between snapshots of [`watch --no-ui`](https://filetrace.mintlify.site/cli/watch).


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