CLIGuides

File operations with the CLI

This guide covers everyday file tasks — uploading, listing, inspecting, organizing, and deleting files from the command line.

For the complete flag reference, see the file and metadata command reference.

Uploading files

Upload a single file:

$uploadcare file upload photo.jpg
UUID                                  SIZE      FILENAME    STORED
a1b2c3d4-e5f6-7890-abcd-ef1234567890  2.4 MB   photo.jpg   true

Upload multiple files:

$uploadcare file upload *.jpg

Upload from a URL:

$uploadcare file upload-from-url https://example.com/image.png

The CLI polls until the upload completes. Use --no-wait to return immediately (not available for upload-from-url — use --timeout to control how long to wait).

Upload with metadata:

$uploadcare file upload photo.jpg --metadata source=camera --metadata project=vacation

Control storage behavior:

$# Don't auto-store (file will be temporary)
>uploadcare file upload photo.jpg --store false
>
># Explicitly store
>uploadcare file upload photo.jpg --store true

Show upload progress:

$uploadcare file upload large-video.mp4 --progress

Listing and filtering files

List files with default settings:

$uploadcare file list

List only stored files, newest first:

$uploadcare file list --stored true --ordering -datetime_uploaded

Get specific fields as JSON:

$uploadcare file list --json uuid,filename,size

Stream all files (not just the first page):

$uploadcare file list --page-all --json uuid,filename

--page-all outputs one JSON object per line (NDJSON), streaming results without loading everything into memory.

Filter with jq:

$# Find images larger than 1 MB
$uploadcare file list --page-all --jq 'select(.size > 1048576 and .is_image == true) | .uuid'

Inspecting files

Get full file details:

$uploadcare file info a1b2c3d4-e5f6-7890-abcd-ef1234567890

Extract specific fields:

$uploadcare file info a1b2c3d4-e5f6-7890-abcd-ef1234567890 --json uuid,size,mime_type
1{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","size":2457600,"mime_type":"image/jpeg"}

Include application data (add-on results):

$uploadcare file info a1b2c3d4-e5f6-7890-abcd-ef1234567890 --include-appdata --json all

Managing file storage

Store files permanently:

$uploadcare file store a1b2c3d4-e5f6-7890-abcd-ef1234567890

Store multiple files:

$uploadcare file store UUID1 UUID2 UUID3

Delete a file:

$uploadcare file delete a1b2c3d4-e5f6-7890-abcd-ef1234567890

Batch delete with piping — delete all unstored files:

$uploadcare file list --page-all --stored false --json uuid | uploadcare file delete --from-stdin

Preview before deleting with dry-run:

$uploadcare file delete UUID1 UUID2 --dry-run

File deletion is permanent. Use --dry-run to preview what will happen before executing destructive operations.

Working with metadata

Metadata attaches custom key-value pairs to files. Keys are lowercase alphanumeric with hyphens (max 64 chars). See the metadata concept page for details.

Set a metadata value:

$uploadcare metadata set a1b2c3d4-e5f6-7890-abcd-ef1234567890 source camera

List all metadata on a file:

$uploadcare metadata list a1b2c3d4-e5f6-7890-abcd-ef1234567890

Get a specific metadata value:

$uploadcare metadata get a1b2c3d4-e5f6-7890-abcd-ef1234567890 source

Delete a metadata key:

$uploadcare metadata delete a1b2c3d4-e5f6-7890-abcd-ef1234567890 source

Copying files

Copy within Uploadcare storage:

$uploadcare file local-copy a1b2c3d4-e5f6-7890-abcd-ef1234567890

This creates a new file with its own UUID. Add --store to store the copy immediately.

Copy to external storage (e.g., S3):

$uploadcare file remote-copy a1b2c3d4-e5f6-7890-abcd-ef1234567890 --target my-s3-bucket

Use --pattern to control the filename on remote storage:

$uploadcare file remote-copy UUID --target my-s3-bucket --pattern "${uuid}/${filename}"

See the S3 integration guide for setting up external storage.

Working with file groups

File groups bundle multiple files under a single group ID. See the file groups concept page for details and the group command reference for all flags.

Create a group from file UUIDs:

$uploadcare group create UUID1 UUID2 UUID3

Create a group from a file list:

$uploadcare file list --page-all --stored true --json uuid | head -5 | uploadcare group create --from-stdin

List groups:

$uploadcare group list --json all

Get group details (includes file list):

$uploadcare group info "a1b2c3d4-e5f6-7890-abcd-ef1234567890~3"