CLICommand reference

File and metadata commands

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

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:

FlagDefaultDescription
--orderingdatetime_uploadedSort order. Prefix with - for descending
--limit100Files per page
--starting-pointStarting point (RFC 3339 datetime)
--storedFilter by stored status (true or false)
--removedfalseInclude removed files
--page-allfalseStream all pages as NDJSON
--include-appdatafalseInclude 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:

FlagDefaultDescription
--include-appdatafalseInclude 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:

FlagDefaultDescription
--storeautoStorage behavior: auto, true, or false
--metadataKey-value pair (repeatable): --metadata key=value
--multipart-threshold10485760Size threshold for multipart upload (bytes)
--force-multipartfalseForce multipart upload
--force-directfalseForce direct upload
--progressfalseShow upload progress on stderr
--dry-runfalseValidate without uploading
--from-stdinfalseRead 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:

FlagDefaultDescription
--storeautoStorage behavior: auto, true, or false
--metadataKey-value pair (repeatable): --metadata key=value
--timeout5mMax wait time for upload
--check-duplicatesfalseCheck for duplicate URLs
--save-duplicatesfalseSave duplicate URL information
--dry-runfalseValidate URLs without uploading
--from-stdinfalseRead 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:

FlagDefaultDescription
--from-stdinfalseRead UUIDs from stdin
--dry-runfalseValidate 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]

Deletion is permanent and cannot be undone. Use --dry-run to preview.

Flags:

FlagDefaultDescription
--from-stdinfalseRead UUIDs from stdin
--dry-runfalseValidate 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:

FlagDefaultDescription
--storefalseStore the copied file
--dry-runfalseValidate 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 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:

FlagDefaultDescription
--targetRemote storage name (required)
--make-publicfalseMake file public on remote storage
--patternFilename pattern (e.g., ${uuid}/${filename})
--dry-runfalseValidate 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}"

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:

FlagDefaultDescription
--dry-runfalseShow 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:

FlagDefaultDescription
--dry-runfalseVerify 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