> ## 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 userfile get

The `cockroach userfile get` [command](/docs/stable/cockroach-commands.md) fetches the files stored in the [user-scoped file storage](/docs/stable/use-userfile-storage.md) which match the provided pattern, using a SQL connection. If no pattern is provided, all files in the specified (or default, if unspecified) user-scoped file storage will be fetched.

## Required privileges

The user must have `CONNECT` [privileges](/docs/stable/security-reference/authorization.md#managing-privileges) on the target database.

A user can only fetch files from their own user-scoped storage, which is accessed through the [userfile URI](/docs/stable/cockroach-userfile-upload.md#file-destination) used during the upload. CockroachDB will revoke all access from every other user in the cluster except users in the `admin` role and users explicitly granted access.

> [!NOTE]
>
> If this is your first interaction with user-scoped file storage, you may see an error indicating that you need `CREATE` privileges on the database. You must first [upload a file](/docs/stable/cockroach-userfile-upload.md) or run a [`BACKUP`](/docs/stable/backup) to `userfile` before attempting to `get` a file.

## Synopsis

Fetch a file:

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

View help:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile get --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 [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/` |
| `--echo-sql` | Reveal the SQL statements sent implicitly by the command-line utility. |
|  `--url` | A [connection URL](/docs/stable/connection-parameters.md#connect-using-a-url) to use instead of the other arguments. **Env Variable:** `COCKROACH_URL` **Default:** no URL |
| `--user` `-u` | The [SQL user](/docs/stable/create-user.md) that will own the client session. **Env Variable:** `COCKROACH_USER` **Default:** `root` |

## Examples

### Get a specific file

To get the file named test-data.csv from the default user-scoped storage location for the current user:

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

### Get a file saved to an explicit local file name

To get a file named test-data.csv from a local directory:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach userfile get test-data.csv /Users/maxroach/Desktop/test-data.csv --certs-dir=certs
```

### Get a file from a non-default userfile URI

If you [uploaded a file to a non-default userfile URI](/docs/stable/cockroach-userfile-upload.md#upload-a-file-to-a-non-default-userfile-uri) (e.g., `userfile://testdb.public.uploads`), use the same URI to fetch it:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
cockroach userfile get userfile://testdb.public.uploads/test-data.csv --certs-dir=certs
```

### Get files that match the provided pattern

To get all files that match a pattern, use \*:

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

## See also

* [`cockroach userfile upload`](/docs/stable/cockroach-userfile-upload)
* [`cockroach userfile delete`](/docs/stable/cockroach-userfile-delete)
* [`cockroach userfile list`](/docs/stable/cockroach-userfile-list)
* [Use `userfile` storage](/docs/stable/use-userfile-storage)
* [`cockroach` Commands Overview](/docs/stable/cockroach-commands)