> 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 operations with the CLI > Upload, list, inspect, store, delete, and copy files using the Uploadcare CLI. This guide covers everyday file tasks — uploading, listing, inspecting, organizing, and deleting files from the command line. > **Tip** > > **Tip:** For the complete flag reference, see the [file, metadata, and tag command reference](/docs/cli/reference/file/). ## Uploading files **Upload a single file:** ```bash uploadcare file upload photo.jpg ``` ``` UUID SIZE FILENAME STORED a1b2c3d4-e5f6-7890-abcd-ef1234567890 2.4 MB photo.jpg true ``` **Upload multiple files:** ```bash uploadcare file upload *.jpg ``` **Upload from a URL:** ```bash 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:** ```bash uploadcare file upload photo.jpg --metadata source=camera --metadata project=vacation ``` **Control storage behavior:** ```bash # 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:** ```bash uploadcare file upload large-video.mp4 --progress ``` ## Listing and filtering files **List files with default settings:** ```bash uploadcare file list ``` **List only stored files, newest first:** ```bash uploadcare file list --stored true --ordering -datetime_uploaded ``` **Get specific fields as JSON:** ```bash uploadcare file list --json uuid,filename,size ``` **Stream all files (not just the first page):** ```bash 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:** ```bash # 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:** ```bash uploadcare file info a1b2c3d4-e5f6-7890-abcd-ef1234567890 ``` **Extract specific fields:** ```bash uploadcare file info a1b2c3d4-e5f6-7890-abcd-ef1234567890 --json uuid,size,mime_type ``` ```json {"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","size":2457600,"mime_type":"image/jpeg"} ``` **Include application data (add-on results):** ```bash uploadcare file info a1b2c3d4-e5f6-7890-abcd-ef1234567890 --include-appdata --json all ``` ## Managing file storage **Store files permanently:** ```bash uploadcare file store a1b2c3d4-e5f6-7890-abcd-ef1234567890 ``` **Store multiple files:** ```bash uploadcare file store UUID1 UUID2 UUID3 ``` **Delete a file:** ```bash uploadcare file delete a1b2c3d4-e5f6-7890-abcd-ef1234567890 ``` **Batch delete with piping — delete all unstored files:** ```bash uploadcare file list --page-all --stored false --json uuid | uploadcare file delete --from-stdin ``` **Preview before deleting with dry-run:** ```bash uploadcare file delete UUID1 UUID2 --dry-run ``` > **Warning** > > **Warning:** 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](/docs/file-metadata/) for details. **Set a metadata value:** ```bash uploadcare metadata set a1b2c3d4-e5f6-7890-abcd-ef1234567890 source camera ``` **List all metadata on a file:** ```bash uploadcare metadata list a1b2c3d4-e5f6-7890-abcd-ef1234567890 ``` **Get a specific metadata value:** ```bash uploadcare metadata get a1b2c3d4-e5f6-7890-abcd-ef1234567890 source ``` **Delete a metadata key:** ```bash uploadcare metadata delete a1b2c3d4-e5f6-7890-abcd-ef1234567890 source ``` ## Copying files **Copy within Uploadcare storage:** ```bash 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):** ```bash uploadcare file remote-copy a1b2c3d4-e5f6-7890-abcd-ef1234567890 --target my-s3-bucket ``` Use `--pattern` to control the filename on remote storage: ```bash uploadcare file remote-copy UUID --target my-s3-bucket --pattern "${uuid}/${filename}" ``` See the [S3 integration guide](/docs/s3-integration/) for setting up external storage. ## Downloading files **Download a single file to the current directory:** ```bash uploadcare file download a1b2c3d4-e5f6-7890-abcd-ef1234567890 ``` **Download to a specific path or stream to stdout:** ```bash uploadcare file download --output ./photo.jpg uploadcare file download --output - > photo.jpg ``` **Mirror all stored files into a local directory with 8 parallel workers:** ```bash uploadcare file list --page-all --stored true --json uuid \ | uploadcare file download --from-stdin --output-dir ./backup --parallel 8 ``` 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:** ```bash uploadcare file download --output thumb.jpg --effects resize/200x/ ``` Effects are silently ignored for non-image files. See the [file download reference](/docs/cli/reference/file/#file-download) for the full flag list. ## Working with file groups File groups bundle multiple files under a single group ID. See the [file groups concept page](/docs/file-groups/) for details and the [group command reference](/docs/cli/reference/group/) for all flags. **Create a group from file UUIDs:** ```bash uploadcare group create UUID1 UUID2 UUID3 ``` **Create a group from a file list:** ```bash uploadcare file list --page-all --stored true --json uuid | head -5 | uploadcare group create --from-stdin ``` **List groups:** ```bash uploadcare group list --json all ``` **Get group details (includes file list):** ```bash uploadcare group info "a1b2c3d4-e5f6-7890-abcd-ef1234567890~3" ```