Output modes and scripting | Uploadcare docs

The CLI supports multiple output modes for both human reading and machine processing. This guide covers how to use them effectively in scripts and workflows.

Output modes

Human-readable (default)

The default output renders formatted tables with colors. Best for interactive terminal use.

$ uploadcare file list

UUID                                  SIZE      FILENAME       STORED
a1b2c3d4-e5f6-7890-abcd-ef1234567890  2.4 MB   photo.jpg      true
b2c3d4e5-f6a7-8901-bcde-f12345678901  890 KB   document.pdf   true

JSON

Use --json for structured output. Pass all for every field, or select specific fields:

$ # All fields
$ uploadcare file info UUID --json all
$ 
$ # Specific fields only
$ uploadcare file info UUID --json uuid,size,mime_type

1 {"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","size":2457600,"mime_type":"image/jpeg"}

NDJSON (streaming)

When listing with --page-all, the CLI streams one JSON object per line (newline-delimited JSON). This works well with line-based tools and avoids loading the entire result set into memory.

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

{"uuid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","filename":"photo.jpg"}
{"uuid":"b2c3d4e5-f6a7-8901-bcde-f12345678901","filename":"document.pdf"}

Quiet

Use -q or --quiet to suppress all non-error output. The exit code indicates success or failure.

$ uploadcare file store UUID -q
$ echo $?  # 0 = success

Verbose

Use -v or --verbose to log HTTP request and response details to stderr. Combine with any other output mode for debugging.

$ uploadcare file info UUID --json all -v

Verbose output goes to stderr, so it doesn’t interfere with JSON output on stdout.

Field selection

Select specific JSON fields to reduce output size — especially useful in scripts and when working with AI agents where token usage matters.

$ # Full output: ~2 KB per file
$ uploadcare file info UUID --json all
$ 
$ # Selected fields: ~50 bytes per file
$ uploadcare file info UUID --json uuid,size

Available fields vary by command. Run any command with --json all to see all available fields, or check the command reference.

Filtering with —jq

The --jq flag applies a jq expression to the JSON output. It implies --json, so you don’t need to specify both.

Extract a single field:

$ uploadcare file info UUID --jq '.uuid'

Filter a list:

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

Reshape output:

$ uploadcare file info UUID --jq '{id: .uuid, type: .mime_type, mb: (.size / 1048576)}'

Count files:

$ uploadcare file list --page-all --jq '.uuid' | wc -l

Composing commands with piping

Commands that accept --from-stdin read UUIDs (or file paths, or URLs) from standard input. This lets you chain commands together.

Delete all unstored files:

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

Store the 10 most recently uploaded files:

$ uploadcare file list --ordering -datetime_uploaded --limit 10 --json uuid | uploadcare file store --from-stdin

Create a group from stored images:

$ uploadcare file list --page-all --stored true --jq 'select(.is_image == true) | .uuid' \
>   | head -20 \
>   | uploadcare group create --from-stdin

Upload files listed in a text file:

$ cat file-paths.txt | uploadcare file upload --from-stdin

The CLI auto-detects whether stdin contains plain text (one value per line) or NDJSON.

Dry-run mode

Use --dry-run on destructive or mutating commands to preview what would happen without making changes.

$ uploadcare file delete UUID1 UUID2 --dry-run

$ uploadcare metadata set UUID source camera --dry-run --json all

1 {"key":"source","current_value":"","new_value":"camera","status":"would_set"}

Dry-run works on: file upload, file upload-from-url, file store, file delete, file local-copy, file remote-copy, metadata set, metadata delete, group create, group delete, webhook create, webhook update, webhook delete, convert document, convert video, addon execute, project create, project update, project delete.

Scripting best practices

Always use --json in scripts. Human-readable output may change between versions; JSON output is stable.

$ UUID=$(uploadcare file upload photo.jpg --json uuid | jq -r '.uuid')

Check exit codes. Don’t parse output to detect errors — use $?:

$ if ! uploadcare file store "$UUID" -q; then
$   echo "Failed to store file" >&2
$   exit 1
$ fi

Handle pagination for large file sets. Use --page-all to stream all results:

$ uploadcare file list --page-all --json uuid | while read -r line; do
$   uuid=$(echo "$line" | jq -r '.uuid')
$   # process each file
$ done

Disable colors in logs. Use --no-color or set NO_COLOR=1 to avoid ANSI escape codes in log files:

$ NO_COLOR=1 uploadcare file list > output.log