CLICommand reference

Convert, add-ons, webhooks, and utilities

Global flags like --json, --jq, -v, and --quiet are available on every command. See Configuration for the full list.

Convert commands

Convert documents and videos stored in Uploadcare. Conversions are asynchronous — by default the CLI polls for completion. Use --no-wait to return the conversion token immediately.

See File conversion and Video processing for details on supported formats.

convert document

Convert a document to another format.

$uploadcare convert document <uuid> [flags]

Flags:

FlagDefaultDescription
--formatTarget format, e.g., pdf, doc, txt (required)
--pagePage number for multi-page documents
--save-in-groupfalseSave multi-page result as file group
--storefalseStore the converted file
--no-waitfalseReturn conversion token without waiting
--timeout5mTimeout when polling for completion
--dry-runfalseValidate without converting

Examples:

$uploadcare convert document UUID --format pdf
$uploadcare convert document UUID --format pdf --store
$uploadcare convert document UUID --format png --page 3
$uploadcare convert document UUID --format pdf --no-wait --json all
$uploadcare convert document UUID --format pdf --dry-run --json all

convert video

Convert a video to another format with optional resizing, quality, and trimming.

$uploadcare convert video <uuid> [flags]

Flags:

FlagDefaultDescription
--formatTarget format, e.g., mp4, webm, ogg
--sizeOutput size, e.g., 640x480
--resize-modepreserve_ratio, change_ratio, scale_crop, or add_padding
--qualitynormal, better, best, lighter, or lightest
--cutTime range, e.g., 000:00:05.000/000:00:15.000
--thumbsNumber of thumbnails to generate
--storefalseStore the converted file
--no-waitfalseReturn conversion token without waiting
--timeout5mTimeout when polling for completion
--dry-runfalseValidate without converting

Examples:

$uploadcare convert video UUID --format mp4
$uploadcare convert video UUID --format mp4 --size 1280x720 --quality better
$uploadcare convert video UUID --format mp4 --cut 000:00:05.000/000:00:15.000
$uploadcare convert video UUID --thumbs 5
$uploadcare convert video UUID --format mp4 --no-wait --json all

Add-on commands

Execute and monitor Uploadcare add-ons on files. Available add-ons:

Add-on nameDescription
uc-clamav-virus-scanVirus scanning (ClamAV)
aws-rekognition-detect-labelsImage labeling (AWS Rekognition)
aws-rekognition-detect-moderation-labelsContent moderation (AWS Rekognition)
remove-bgBackground removal

See Malware protection, Object recognition, and Background removal for details.

addon execute

Run an add-on on a file. By default, polls until execution completes.

$uploadcare addon execute <addon-name> <file-uuid> [flags]

Flags:

FlagDefaultDescription
--paramsAdd-on parameters as JSON
--no-waitfalseReturn request ID without waiting
--timeout5mTimeout when polling for completion
--dry-runfalseValidate without executing

Examples:

$uploadcare addon execute uc-clamav-virus-scan UUID
$uploadcare addon execute aws-rekognition-detect-labels UUID --json all
$uploadcare addon execute remove-bg UUID --json all
$uploadcare addon execute uc-clamav-virus-scan UUID --no-wait --json all
$uploadcare addon execute aws-rekognition-detect-labels UUID --params '{"max_labels": 5}'
$uploadcare addon execute uc-clamav-virus-scan UUID --dry-run

addon status

Check the status of an add-on execution.

$uploadcare addon status <addon-name> <request-id>

Status values: in_progress, done, error.

JSON fields: status, result

Examples:

$uploadcare addon status uc-clamav-virus-scan req-12345-abcde
$uploadcare addon status uc-clamav-virus-scan req-12345-abcde --json all

Webhook commands

Manage webhooks for the current project. Webhooks deliver HTTP POST notifications to your endpoint when events occur.

Valid events: file.uploaded, file.stored, file.deleted, file.info_updated.

See the Webhooks concept page for details on event payloads and delivery.

webhook list

List all webhooks for the current project.

$uploadcare webhook list

JSON fields: id, target_url, event, is_active, signing_secret, datetime_created, datetime_updated

Examples:

$uploadcare webhook list
$uploadcare webhook list --json all
$uploadcare webhook list --json id,target_url,event,is_active

webhook create

Create a new webhook.

$uploadcare webhook create <target-url> [flags]

Flags:

FlagDefaultDescription
--eventfile.uploadedEvent type
--activetrueWhether the webhook is active
--signing-secretSecret for webhook signature verification
--dry-runfalseValidate without creating

Examples:

$uploadcare webhook create https://example.com/hooks/upload
$uploadcare webhook create https://example.com/hooks/delete --event file.deleted
$uploadcare webhook create https://example.com/hooks/upload --active=false --signing-secret my-secret
$uploadcare webhook create https://example.com/hooks/upload --dry-run --json all

webhook update

Update an existing webhook.

$uploadcare webhook update <webhook-id> [flags]

Flags:

FlagDefaultDescription
--target-urlNew target URL
--eventNew event type
--activeWhether the webhook is active (true or false)
--signing-secretNew signing secret
--dry-runfalseShow what would change without applying

Examples:

$uploadcare webhook update 12345 --target-url https://example.com/new-hook
$uploadcare webhook update 12345 --active false
$uploadcare webhook update 12345 --event file.stored --active true
$uploadcare webhook update 12345 --target-url https://example.com/new --dry-run --json all

webhook delete

Delete a webhook.

$uploadcare webhook delete <webhook-id> [flags]

Flags:

FlagDefaultDescription
--dry-runfalseVerify without deleting

Examples:

$uploadcare webhook delete 12345
$uploadcare webhook delete 12345 --json all
$uploadcare webhook delete 12345 --dry-run

Utility commands

url-api

Reference for the URL API (CDN transformations). Outputs transformation operations and syntax.

$uploadcare url-api

api-schema

Print the complete CLI command tree as a JSON schema. Useful for AI agents and tooling that need to discover all available commands, flags, and examples programmatically.

$uploadcare api-schema
$# List all available command paths
$uploadcare api-schema | jq -r '.commands[].path'
$
$# Count total commands
$uploadcare api-schema | jq '.commands | length'

version

Print CLI version, commit, build date, and platform info.

$uploadcare version
$uploadcare version --json all

JSON fields: version, commit, date, go, os, arch

completion

Generate shell completion scripts for your shell.

$# Bash
$uploadcare completion bash > /etc/bash_completion.d/uploadcare
$
$# Zsh
$uploadcare completion zsh > "${fpath[1]}/_uploadcare"
$
$# Fish
$uploadcare completion fish > ~/.config/fish/completions/uploadcare.fish