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

# cockroach userfile list

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

The `cockroach userfile list` <InternalLink path="cockroach-commands">command</InternalLink> lists the files stored in the <InternalLink path="use-userfile-storage">user-scoped file storage</InternalLink> which match the <InternalLink path="cockroach-userfile-upload#file-destination">provided pattern</InternalLink>, using a SQL connection. If no pattern is provided, all files in the specified (or default, if unspecified) user scoped file storage will be listed.

## Required privileges

The user must have the `CREATE` <InternalLink path="security-reference/authorization#managing-privileges">privilege</InternalLink> on the target database. CockroachDB will proactively grant the user `GRANT`, `SELECT`, `INSERT`, `DROP`, `DELETE` on the metadata and file tables.

A user can only view files in their own user-scoped storage, which is accessed through the <InternalLink path="cockroach-userfile-upload#file-destination">userfile URI</InternalLink> used during the upload. CockroachDB will revoke all access from every other user in the cluster except users in the `admin` role.

## Synopsis

View files:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile list <file | dir> [flags]
```

View help:

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

## Flags

| Flag                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--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 <InternalLink path="cockroach-cert">certificate directory</InternalLink> containing the CA and client certificates and client key.<br /><br />**Env Variable:** `COCKROACH_CERTS_DIR`<br />**Default:** `${HOME}/.cockroach-certs/`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--echo-sql`           | Reveal the SQL statements sent implicitly by the command-line utility.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--url`                | A <InternalLink path="connection-parameters#connect-using-a-url">connection URL</InternalLink> to use instead of the other arguments.<br /><br />**Env Variable:** `COCKROACH_URL`<br />**Default:** no URL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--user`<br />`-u`     | The <InternalLink path="create-user">SQL user</InternalLink> that will own the client session.<br /><br />**Env Variable:** `COCKROACH_USER`<br />**Default:** `root`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## Examples

### List all files in the default storage

If the file or directory is not specified, all files in the default user-scoped storage (`userfile://defaultdb.public.userfiles_$user/`) will be listed:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile list --certs-dir=certs
```

```
userfile://defaultdb.public.userfiles_root/test-data-2.csv
userfile://defaultdb.public.userfiles_root/test-data.csv
userfile://defaultdb.public.userfiles_root/test-upload/test-data.csv
```

### List a specific file

To list all files in a specified directory:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile list test-data.csv --certs-dir=certs
```

```
userfile://defaultdb.public.userfiles_root/test-data.csv
```

### List files that match the provided pattern

To list all files that match a pattern, use `*`:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile list '*.csv' --certs-dir=certs
```

```
userfile://defaultdb.public.userfiles_root/test-data-2.csv
userfile://defaultdb.public.userfiles_root/test-data.csv
```

### List files from a non-default userfile URI

If you <InternalLink path="cockroach-userfile-upload#upload-a-file-to-a-non-default-userfile-uri">uploaded a file to a non-default userfile URI</InternalLink> (e.g., `userfile://testdb.public.uploads`):

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach userfile upload /Users/maxroach/Desktop/test-data.csv userfile://testdb.public.uploads/test-data.csv
```

Use the same URI to view it:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach userfile list userfile://testdb.public.uploads
```

## See also

* <InternalLink path="cockroach-userfile-upload">`cockroach userfile upload`</InternalLink>
* <InternalLink path="cockroach-userfile-delete">`cockroach userfile delete`</InternalLink>
* <InternalLink path="cockroach-userfile-get">`cockroach userfile get`</InternalLink>
* <InternalLink path="use-userfile-storage">Use `userfile` storage</InternalLink>
* <InternalLink path="cockroach-commands">`cockroach` Commands Overview</InternalLink>
* <InternalLink path="import">`IMPORT`</InternalLink>
* <InternalLink path="import-into">`IMPORT INTO`</InternalLink>