> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# Output modes and scripting

> Control CLI output with JSON, NDJSON, field selection, jq filtering, and piping for scripting and automation.

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.

```bash
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:

```bash
# All fields
uploadcare file info UUID --json all

# Specific fields only
uploadcare file info UUID --json uuid,size,mime_type
```

```json
{"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.

```bash
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.

```bash
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.

```bash
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.

```bash
# 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](/docs/cli/reference/file/).

## Filtering with --jq

The `--jq` flag applies a [jq](https://jqlang.github.io/jq/) expression to the JSON output.
It implies `--json`, so you don't need to specify both.

**Extract a single field:**

```bash
uploadcare file info UUID --jq '.uuid'
```

**Filter a list:**

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

**Reshape output:**

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

## 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:**

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

**Store the 10 most recently uploaded files:**

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

**Create a group from stored images:**

```bash
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:**

```bash
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.

```bash
uploadcare file delete UUID1 UUID2 --dry-run
```

```bash
uploadcare metadata set UUID source camera --dry-run --json all
```

```json
{"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`, `file download`, `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.

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

**Check exit codes.** Don't parse output to detect errors. Use `$?`:

```bash
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:

```bash
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:

```bash
NO_COLOR=1 uploadcare file list > output.log
```