> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# cockroach debug list-files

The `cockroach debug list-files` [command](/docs/stable/cockroach-commands.md) shows the files that will be collected by using [`cockroach debug zip`](/docs/stable/cockroach-debug-zip).

> [!NOTE]
>
> The files listed include logs, heap profiles, goroutine dumps, and CPU profiles. Other [files](/docs/stable/cockroach-debug-zip.md#files) generated by `cockroach debug zip` are not listed by `cockroach debug list-files`.

## Subcommands

While the `cockroach debug` command has a few subcommands, users are expected to use only the [`zip`](/docs/stable/cockroach-debug-zip), [`upload`](/docs/stable/cockroach-debug-upload), [`encryption-active-key`](/docs/stable/cockroach-debug-encryption-active-key), [`merge-logs`](/docs/stable/cockroach-debug-merge-logs), [`list-files`](/docs/stable/cockroach-debug-list-files), [`tsdump`](/docs/stable/cockroach-debug-tsdump), and [`ballast`](/docs/stable/cockroach-debug-ballast) subcommands.

We recommend using the [`encryption-decrypt`](/docs/stable/cockroach-debug-encryption-decrypt) and [`job-trace`](/docs/stable/cockroach-debug-job-trace) subcommands only when directed by the [Cockroach Labs support team](/docs/stable/support-resources.md).

The other `debug` subcommands are useful only to Cockroach Labs. Output of `debug` commands may contain sensitive or secret information.

## Synopsis

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug list-files {flags}
```

## Flags

The `debug list-files` subcommand supports the following [general-use](#general), [client connection](#client-connection), and [logging](#logging) flags.

### General

| Flag | Description |
| - | - |
| `--exclude-files` | [Files](/docs/stable/cockroach-debug-zip.md#files) to exclude from the generated `.zip`. This can be used to limit the size of the generated `.zip`, and affects logs, heap profiles, goroutine dumps, and/or CPU profiles. The files are specified as a comma-separated list of [glob patterns](https://wikipedia.org/wiki/Glob_\(programming\)). For example: `--exclude-files=*.log` Note that this flag is applied *after* `--include_files`. |
| `--exclude-nodes` | Specify nodes to exclude from inspection as a comma-separated list or range of node IDs. For example: `--exclude-nodes=1,10,13-15` |
| `--files-from` | Start timestamp for log file, goroutine dump, and heap profile collection. This can be used to limit the size of the generated `.zip`, which is increased by these files. The timestamp uses the format `YYYY-MM-DD`, followed optionally by `HH:MM:SS` or `HH:MM`. For example: `--files-from='2021-07-01 15:00'` When specifying a narrow time window, we recommend adding extra seconds/minutes to account for uncertainties such as clock drift. **Default:** 48 hours before now |
| `--files-until` | End timestamp for log file, goroutine dump, and heap profile collection. This can be used to limit the size of the generated `.zip`, which is increased by these files. The timestamp uses the format `YYYY-MM-DD`, followed optionally by `HH:MM:SS` or `HH:MM`. For example: `--files-until='2021-07-01 16:00'` When specifying a narrow time window, we recommend adding extra seconds/minutes to account for uncertainties such as clock drift. **Default:** 24 hours beyond now (to include files created during `.zip` creation) |
| `--format` | Specify a format to display table rows. This can be `tsv`, `csv`, `table`, `records`, `sql`, `raw`, or `html`. **Default:** `table` (interactive sessions), `tsv` (non-interactive sessions) |
| `--include-files` | [Files](/docs/stable/cockroach-debug-zip.md#files) to include in the generated `.zip`. This can be used to limit the size of the generated `.zip`, and affects logs, heap profiles, goroutine dumps, and/or CPU profiles. The files are specified as a comma-separated list of [glob patterns](https://wikipedia.org/wiki/Glob_\(programming\)). For example: `--include-files=*.pprof` Note that this flag is applied *before* `--exclude-files`. |
| `--nodes` | Specify nodes to inspect as a comma-separated list or range of node IDs. For example: `--nodes=1,10,13-15` |

### Client connection

| Flag | Description |
| - | - |
|  `--url` | A [connection URL](/docs/stable/connection-parameters.md#connect-using-a-url) to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run [`cockroach convert-url`](/docs/stable/connection-parameters#convert-a-url-for-different-drivers). **Env Variable:** `COCKROACH_URL` **Default:** no URL |
| `--host` | The server host and port number to connect to. This can be the address of any node in the cluster.  **Env Variable:** `COCKROACH_HOST` **Default:** `localhost:26257` |
| `--port` `-p` | The server port to connect to. Note: The port number can also be specified via `--host`.  **Env Variable:** `COCKROACH_PORT` **Default:** `26257` |
| `--user` `-u` | The [SQL user](/docs/stable/create-user.md) that will own the client session. **Env Variable:** `COCKROACH_USER` **Default:** `root` |
| `--insecure` | Use an insecure connection. **Env Variable:** `COCKROACH_INSECURE` **Default:** `false` |
|  `--cert-principal-map` | A comma-separated list of `<cert-principal:<db-principal` mappings. This allows mapping the principal in a cert to a DB principal such as `node` or `root` or any SQL user. This is intended for use in situations where the certificate management system places restrictions on the `Subject.CommonName` or `SubjectAlternateName` fields in the certificate (e.g., disallowing a `CommonName` like `node` or `root`). If multiple mappings are provided for the same `<cert-principal`, the last one specified in the list takes precedence. A principal not specified in the map is passed through as-is via the identity function. A cert is allowed to authenticate a DB principal if the DB principal name is contained in the mapped `CommonName` or DNS-type `SubjectAlternateName` fields. |
| `--certs-dir` | The path to the [certificate directory](/docs/stable/cockroach-cert.md) containing the CA and client certificates and client key. **Env Variable:** `COCKROACH_CERTS_DIR` **Default:** `${HOME}/.cockroach-certs/` |
| `--cluster-name` | The cluster name to use to verify the cluster's identity. If the cluster has a cluster name, you must include this flag. For more information, see [`cockroach start`](/docs/stable/cockroach-start#general). |
| `--disable-cluster-name-verification` | Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see [`cockroach start`](/docs/stable/cockroach-start#general). |

### Logging

While the `cockroach debug` command has a few subcommands, users are expected to use only the [`zip`](/docs/stable/cockroach-debug-zip), [`upload`](/docs/stable/cockroach-debug-upload), [`encryption-active-key`](/docs/stable/cockroach-debug-encryption-active-key), [`merge-logs`](/docs/stable/cockroach-debug-merge-logs), [`list-files`](/docs/stable/cockroach-debug-list-files), [`tsdump`](/docs/stable/cockroach-debug-tsdump), and [`ballast`](/docs/stable/cockroach-debug-ballast) subcommands.

We recommend using the [`encryption-decrypt`](/docs/stable/cockroach-debug-encryption-decrypt) and [`job-trace`](/docs/stable/cockroach-debug-job-trace) subcommands only when directed by the [Cockroach Labs support team](/docs/stable/support-resources.md).

The other `debug` subcommands are useful only to Cockroach Labs. Output of `debug` commands may contain sensitive or secret information.

## Examples

### List all collected files

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug list-files
```

The files listed include logs, heap profiles, goroutine dumps, and CPU profiles. Other [files](/docs/stable/cockroach-debug-zip.md#files) generated by `cockroach debug zip` are not listed by `cockroach debug list-files`.

### List all collected log files

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug list-files --include-files=*.log
```

### List all collected files (TSV format)

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug list-files --format=tsv
```