File, metadata, and tag commands

These commands manage files, their metadata, and tags through the REST API and Upload API.

Tip: Global flags like --json, --jq, -v, and --quiet are available on every command. See Configuration for the full list.

file list

List files in the current project.

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:

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.

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:

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.

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:

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.

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:

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.

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:

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.

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

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:

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.

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:

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.

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:

# 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 for setup instructions.

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:

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.

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:

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.

uploadcare metadata list <file-uuid>

Examples:

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.

uploadcare metadata get <file-uuid> <key>

Examples:

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

metadata set

Set a metadata key-value pair.

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:

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.

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

Flags:

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

Examples:

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

List a file’s tags.

uploadcare tag list <file-uuid>

JSON fields: tags

Examples:

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.

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:

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.

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:

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

tag clear

Remove all tags from a file.

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:

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