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.
Upload a single file:
Upload multiple files:
Upload from a URL:
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:
Control storage behavior:
Show upload progress:
List files with default settings:
List only stored files, newest first:
Get specific fields as JSON:
Stream all files (not just the first page):
--page-all outputs one JSON object per line (NDJSON), streaming results without loading
everything into memory.
Filter with jq:
Get full file details:
Extract specific fields:
Include application data (add-on results):
Store files permanently:
Store multiple files:
Delete a file:
Batch delete with piping — delete all unstored files:
Preview before deleting with dry-run:
File deletion is permanent. Use --dry-run to preview what will happen before executing
destructive operations.
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:
List all metadata on a file:
Get a specific metadata value:
Delete a metadata key:
Copy within Uploadcare storage:
This creates a new file with its own UUID. Add --store to store the copy immediately.
Copy to external storage (e.g., S3):
Use --pattern to control the filename on remote storage:
See the S3 integration guide for setting up external storage.
Download a single file to the current directory:
Download to a specific path or stream to stdout:
Mirror all stored files into a local directory with 8 parallel workers:
Use --name-template to control filenames in batch mode (placeholders:
${uuid}, ${filename}, ${ext}, ${effects}). Existing files are skipped unless
you pass --replace.
Apply a CDN transformation while downloading:
Effects are silently ignored for non-image files. See the file download reference for the full flag list.
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:
Create a group from a file list:
List groups:
Get group details (includes file list):