> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# File, metadata, and tag commands

> Complete reference for Uploadcare CLI file, metadata, and tag commands: syntax, flags, and examples.

These commands manage files, their metadata, and tags through the [REST API](/docs/api/rest/) and [Upload API](/docs/api/upload/).

> **Tip**
>
> **Tip:** Global flags like `--json`, `--jq`, `-v`, and `--quiet` are available on every command.
> See [Configuration](/docs/cli/configuration/#global-flags) for the full list.

## file list

List files in the current project.

```bash
uploadcare file list [flags]
```

**Flags:**

| Flag                | Default             | Description                                 |
| ------------------- | ------------------- | ------------------------------------------- |
| `--ordering`        | `datetime_uploaded` | Sort order. Prefix with `-` for descending  |
| `--limit`           | `100`               | Files per page                              |
| `--starting-point`  |                     | Starting point (RFC 3339 datetime)          |
| `--stored`          |                     | Filter by stored status (`true` or `false`) |
| `--removed`         | `false`             | Include removed files                       |
| `--page-all`        | `false`             | Stream all pages as NDJSON                  |
| `--include-appdata` | `false`             | Include application data                    |

**JSON fields:** `uuid`, `size`, `filename`, `mime_type`, `is_image`, `is_stored`, `is_ready`, `datetime_uploaded`, `datetime_stored`, `datetime_removed`, `original_file_url`, `metadata`, `appdata`

**Examples:**

```bash
uploadcare file list --json all
uploadcare file list --stored true --ordering -datetime_uploaded --json uuid,size,filename
uploadcare file list --page-all --json uuid
uploadcare file list --page-all --stored false --json uuid | uploadcare file delete --from-stdin
```

---

## file info

Get details for a single file.

```bash
uploadcare file info <uuid> [flags]
```

**Flags:**

| Flag                | Default | Description                               |
| ------------------- | ------- | ----------------------------------------- |
| `--include-appdata` | `false` | Include application data (add-on results) |

**JSON fields:** `uuid`, `size`, `filename`, `mime_type`, `is_image`, `is_stored`, `is_ready`, `datetime_uploaded`, `datetime_stored`, `datetime_removed`, `original_file_url`, `metadata`, `appdata`

**Examples:**

```bash
uploadcare file info 740e1b8c-1ad8-4324-b7ec-112345678900
uploadcare file info 740e1b8c-1ad8-4324-b7ec-112345678900 --json original_file_url,size
uploadcare file info 740e1b8c-1ad8-4324-b7ec-112345678900 --include-appdata --json all
```

---

## file upload

Upload files from your local filesystem.

```bash
uploadcare file upload <path>... [flags]
```

Files smaller than 10 MB use direct upload; larger files use multipart upload automatically.

**Flags:**

| Flag                    | Default    | Description                                         |
| ----------------------- | ---------- | --------------------------------------------------- |
| `--store`               | `auto`     | Storage behavior: `auto`, `true`, or `false`        |
| `--metadata`            |            | Key-value pair (repeatable): `--metadata key=value` |
| `--multipart-threshold` | `10485760` | Size threshold for multipart upload (bytes)         |
| `--force-multipart`     | `false`    | Force multipart upload                              |
| `--force-direct`        | `false`    | Force direct upload                                 |
| `--progress`            | `false`    | Show upload progress on stderr                      |
| `--dry-run`             | `false`    | Validate without uploading                          |
| `--from-stdin`          | `false`    | Read file paths from stdin                          |

**JSON fields:** `uuid`, `size`, `filename`, `mime_type`, `is_image`, `is_stored`, `is_ready`, `datetime_uploaded`, `original_file_url`, `metadata`

**Examples:**

```bash
uploadcare file upload photo.jpg
uploadcare file upload photo.jpg --store true
uploadcare file upload photo.jpg --metadata source=camera --metadata project=vacation
uploadcare file upload *.jpg --json uuid,filename,size
uploadcare file upload photo.jpg --dry-run --json all
find ./images -name '*.png' | uploadcare file upload --from-stdin --json uuid
```

---

## file upload-from-url

Upload a file from a URL. The CLI polls until the upload completes.

```bash
uploadcare file upload-from-url <url>... [flags]
```

**Flags:**

| Flag                 | Default | Description                                         |
| -------------------- | ------- | --------------------------------------------------- |
| `--store`            | `auto`  | Storage behavior: `auto`, `true`, or `false`        |
| `--metadata`         |         | Key-value pair (repeatable): `--metadata key=value` |
| `--timeout`          | `5m`    | Max wait time for upload                            |
| `--check-duplicates` | `false` | Check for duplicate URLs                            |
| `--save-duplicates`  | `false` | Save duplicate URL information                      |
| `--dry-run`          | `false` | Validate URLs without uploading                     |
| `--from-stdin`       | `false` | Read URLs from stdin                                |

**JSON fields:** `uuid`, `size`, `filename`, `mime_type`, `is_image`, `is_stored`, `is_ready`, `datetime_uploaded`, `original_file_url`, `metadata`

**Examples:**

```bash
uploadcare file upload-from-url https://example.com/photo.jpg
uploadcare file upload-from-url https://example.com/photo.jpg --store true
uploadcare file upload-from-url https://example.com/a.jpg https://example.com/b.jpg --json uuid
uploadcare file upload-from-url https://example.com/photo.jpg --dry-run --json all
```

---

## file store

Store files permanently. Accepts one or more UUIDs.

```bash
uploadcare file store <uuid>... [flags]
```

**Flags:**

| Flag           | Default | Description              |
| -------------- | ------- | ------------------------ |
| `--from-stdin` | `false` | Read UUIDs from stdin    |
| `--dry-run`    | `false` | Validate without storing |

Returns exit code 1 for partial failures. The `problems` field in JSON output contains per-file errors.

**JSON fields:** `files`, `problems`

**Examples:**

```bash
uploadcare file store 740e1b8c-1ad8-4324-b7ec-112345678900
uploadcare file store UUID1 UUID2 UUID3
uploadcare file list --page-all --stored false --json uuid | uploadcare file store --from-stdin
uploadcare file store UUID1 UUID2 --dry-run --json all
```

---

## file delete

Delete files permanently. Accepts one or more UUIDs.

```bash
uploadcare file delete <uuid>... [flags]
```

> **Warning**
>
> **Warning:** Deletion is permanent and cannot be undone. Use `--dry-run` to preview.

**Flags:**

| Flag           | Default | Description               |
| -------------- | ------- | ------------------------- |
| `--from-stdin` | `false` | Read UUIDs from stdin     |
| `--dry-run`    | `false` | Validate without deleting |

Returns exit code 1 for partial failures.

**JSON fields:** `files`, `problems`

**Examples:**

```bash
uploadcare file delete 740e1b8c-1ad8-4324-b7ec-112345678900
uploadcare file delete UUID1 UUID2 UUID3
uploadcare file list --page-all --stored false --json uuid | uploadcare file delete --from-stdin
uploadcare file delete UUID1 UUID2 --dry-run --json all
```

---

## file local-copy

Create a copy of a file within Uploadcare storage. The copy gets a new UUID.

```bash
uploadcare file local-copy <uuid> [flags]
```

**Flags:**

| Flag        | Default | Description              |
| ----------- | ------- | ------------------------ |
| `--store`   | `false` | Store the copied file    |
| `--dry-run` | `false` | Validate without copying |

**JSON fields:** `uuid`, `size`, `filename`, `mime_type`, `is_image`, `is_stored`, `is_ready`, `datetime_uploaded`, `original_file_url`

**Examples:**

```bash
uploadcare file local-copy 740e1b8c-1ad8-4324-b7ec-112345678900
uploadcare file local-copy 740e1b8c-1ad8-4324-b7ec-112345678900 --store
```

---

## file download

Download files from the Uploadcare CDN to the local filesystem.

```bash
uploadcare file download <uuid>... [flags]
```

Accepts UUIDs as positional arguments, from stdin (`--from-stdin`), or both. Single-UUID
mode writes to `--output <path>` (use `-` to stream to stdout), or to `./<filename>` when
omitted. Batch mode (multiple UUIDs or `--from-stdin`) requires `--output-dir` and
expands `--name-template` per file.

**Flags:**

| Flag              | Default         | Description                                                                                      |
| ----------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| `--output`        |                 | Output path for a single file (use `-` for stdout)                                               |
| `--output-dir`    |                 | Output directory for batch downloads                                                             |
| `--name-template` | `${uuid}${ext}` | Filename template for batch mode. Placeholders: `${uuid}`, `${filename}`, `${ext}`, `${effects}` |
| `--effects`       |                 | CDN effects path to apply to images (e.g. `resize/200x/`). Silently ignored for non-image files  |
| `--replace`       | `false`         | Overwrite existing files; without it, existing paths are skipped                                 |
| `--parallel`      | `1`             | Number of concurrent downloads (max `32`)                                                        |
| `--progress`      | `false`         | Show download progress on stderr                                                                 |
| `--from-stdin`    | `false`         | Read UUIDs from stdin                                                                            |
| `--dry-run`       | `false`         | Resolve paths without downloading                                                                |

**JSON fields:** `uuid`, `path`, `size`, `source_url`, `status` (`downloaded`, `skipped`, or `dry-run`)

**Examples:**

```bash
# Download one file to ./<filename>
uploadcare file download 740e1b8c-1ad8-4324-b7ec-112345678900

# Download to a specific path
uploadcare file download <uuid> --output ./photo.jpg

# Stream to stdout
uploadcare file download <uuid> --output - > photo.jpg

# Mirror all stored files into ./backup, 8 concurrent workers
uploadcare file list --page-all --stored true --json uuid \
  | uploadcare file download --from-stdin --output-dir ./backup --parallel 8

# Apply a CDN transformation while downloading (resize to 200px wide)
uploadcare file download <uuid> --output thumb.jpg --effects resize/200x/

# Dry run: show what would be downloaded
uploadcare file download <uuid1> <uuid2> --output-dir ./out --dry-run --json all
```

---

## file remote-copy

Copy a file to an external storage target (e.g., Amazon S3).
See [Copy files to S3](/docs/s3-integration/) for setup instructions.

```bash
uploadcare file remote-copy <uuid> [flags]
```

**Flags:**

| Flag            | Default | Description                                    |
| --------------- | ------- | ---------------------------------------------- |
| `--target`      |         | Remote storage name (required)                 |
| `--make-public` | `false` | Make file public on remote storage             |
| `--pattern`     |         | Filename pattern (e.g., `${uuid}/${filename}`) |
| `--dry-run`     | `false` | Validate without copying                       |

**JSON fields:** `result`, `already_exists`

**Examples:**

```bash
uploadcare file remote-copy 740e1b8c-1ad8-4324-b7ec-112345678900 --target my-s3-bucket
uploadcare file remote-copy UUID --target my-s3-bucket --make-public
uploadcare file remote-copy UUID --target my-s3-bucket --pattern "${uuid}/${filename}"
```

---

## file search

Search files by text, fields, ranges, and tags.

```bash
uploadcare file search [query] [flags]
```

At least one query or filter is required. The optional query and each `--phrase` value must be at least four characters; `--exact` only requires a non-empty value. The API returns at most the first 1000 matches: `--offset` plus `--limit` cannot exceed 1000, and `--page-all` stops after the first 1000. The search index updates asynchronously, so very recent file, metadata, or tag changes may not appear immediately. Removed files are excluded.

Pages are filled by following the API's next cursor, so offset-stepped pages may occasionally overlap. Prefer `--page-all` when completeness matters.

**Flags:**

| Flag                | Default | Description                                                                       |
| ------------------- | ------- | --------------------------------------------------------------------------------- |
| `--exact`           |         | Exact match as `field=value` (repeatable)                                         |
| `--phrase`          |         | Phrase match as `field=value` (one per field; repeatable across different fields) |
| `--fuzziness`       | `false` | Enable fuzzy text and phrase matching                                             |
| `--tag-all`         |         | Match every tag listed (repeatable)                                               |
| `--tag-any`         |         | Match at least one tag listed (repeatable)                                        |
| `--tag-none`        |         | Exclude files matching any tag listed (repeatable)                                |
| `--is-image`        |         | Filter by image status (`true` or `false`)                                        |
| `--size-gt`         | `0`     | File size greater than, in bytes                                                  |
| `--size-gte`        | `0`     | File size greater than or equal to, in bytes                                      |
| `--size-lt`         | `0`     | File size less than, in bytes                                                     |
| `--size-lte`        | `0`     | File size less than or equal to, in bytes                                         |
| `--uploaded-gt`     |         | Uploaded after this RFC 3339 timestamp                                            |
| `--uploaded-gte`    |         | Uploaded at or after this RFC 3339 timestamp                                      |
| `--uploaded-lt`     |         | Uploaded before this RFC 3339 timestamp                                           |
| `--uploaded-lte`    |         | Uploaded at or before this RFC 3339 timestamp                                     |
| `--sort`            |         | Sort field, optionally prefixed with `-` for descending (repeatable, max 4)       |
| `--limit`           | `20`    | Matches per page (1-100)                                                          |
| `--offset`          | `0`     | Result offset (`offset + limit` cannot exceed 1000)                               |
| `--page-all`        | `false` | Stream all result pages (up to the first 1000 matches)                            |
| `--include-appdata` | `false` | Include application data                                                          |

**JSON fields:** `uuid`, `size`, `filename`, `mime_type`, `is_image`, `is_stored`, `is_ready`, `datetime_uploaded`, `datetime_stored`, `datetime_removed`, `url`, `original_file_url`, `metadata`, `tags`, `appdata`, `highlight`

**Examples:**

```bash
uploadcare file search invoice --exact detected_mime_type=application/pdf --tag-all approved --tag-none archived --sort score --sort=-datetime_uploaded
uploadcare file search --exact 'metadata[camera]=Canon' --json uuid,filename,tags,highlight
```

---

## metadata list

List all metadata key-value pairs for a file.

```bash
uploadcare metadata list <file-uuid>
```

**Examples:**

```bash
uploadcare metadata list 740e1b8c-1ad8-4324-b7ec-112345678900
uploadcare metadata list 740e1b8c-1ad8-4324-b7ec-112345678900 --json all
```

---

## metadata get

Get a single metadata value.

```bash
uploadcare metadata get <file-uuid> <key>
```

**Examples:**

```bash
uploadcare metadata get 740e1b8c-1ad8-4324-b7ec-112345678900 source
```

---

## metadata set

Set a metadata key-value pair.

```bash
uploadcare metadata set <file-uuid> <key> <value> [flags]
```

**Flags:**

| Flag        | Default | Description                             |
| ----------- | ------- | --------------------------------------- |
| `--dry-run` | `false` | Show what would change without applying |

**JSON fields:** `key`, `value` (normal); `key`, `current_value`, `new_value`, `status` (dry-run)

**Examples:**

```bash
uploadcare metadata set 740e1b8c-1ad8-4324-b7ec-112345678900 source camera
uploadcare metadata set 740e1b8c-1ad8-4324-b7ec-112345678900 source camera --dry-run --json all
```

---

## metadata delete

Delete a metadata key.

```bash
uploadcare metadata delete <file-uuid> <key> [flags]
```

**Flags:**

| Flag        | Default | Description                        |
| ----------- | ------- | ---------------------------------- |
| `--dry-run` | `false` | Verify key exists without deleting |

**Examples:**

```bash
uploadcare metadata delete 740e1b8c-1ad8-4324-b7ec-112345678900 source
uploadcare metadata delete 740e1b8c-1ad8-4324-b7ec-112345678900 source --dry-run
```

---

## tag list

List a file's tags.

```bash
uploadcare tag list <file-uuid>
```

**JSON fields:** `tags`

**Examples:**

```bash
uploadcare tag list 740e1b8c-1ad8-4324-b7ec-112345678900
```

---

## tag replace

Replace a file's complete tag set. At least one tag is required; to remove every tag, use `tag clear` instead.

```bash
uploadcare tag replace <file-uuid> <tag>... [flags]
```

**Flags:**

| Flag        | Default | Description                             |
| ----------- | ------- | --------------------------------------- |
| `--dry-run` | `false` | Show what would change without applying |

**JSON fields:** `tags`, `added`, `deleted` (`status` also included with `--dry-run`)

**Examples:**

```bash
uploadcare tag replace 740e1b8c-1ad8-4324-b7ec-112345678900 cat animal cute
uploadcare tag replace 740e1b8c-1ad8-4324-b7ec-112345678900 cat --dry-run --json all
```

---

## tag update

Atomically add and delete tags on a file.

```bash
uploadcare tag update <file-uuid> [flags]
```

**Flags:**

| Flag        | Default | Description                             |
| ----------- | ------- | --------------------------------------- |
| `--add`     |         | Tag to add (repeatable)                 |
| `--delete`  |         | Tag to delete (repeatable)              |
| `--dry-run` | `false` | Show what would change without applying |

**JSON fields:** `tags`, `added`, `deleted` (`status` also included with `--dry-run`)

**Examples:**

```bash
uploadcare tag update 740e1b8c-1ad8-4324-b7ec-112345678900 --add cat --add animal --delete draft
```

---

## tag clear

Remove all tags from a file.

```bash
uploadcare tag clear <file-uuid> [flags]
```

**Flags:**

| Flag        | Default | Description                             |
| ----------- | ------- | --------------------------------------- |
| `--dry-run` | `false` | Show what would change without applying |

**JSON fields:** `tags`, `added`, `deleted` (`status` also included with `--dry-run`)

**Examples:**

```bash
uploadcare tag clear 740e1b8c-1ad8-4324-b7ec-112345678900
uploadcare tag clear 740e1b8c-1ad8-4324-b7ec-112345678900 --dry-run
```