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:

Flag	Default	Description
`--format`		Target format, e.g., `pdf`, `doc`, `txt` (required)
`--page`		Page number for multi-page documents
`--save-in-group`	`false`	Save multi-page result as file group
`--store`	`false`	Store the converted file
`--no-wait`	`false`	Return conversion token without waiting
`--timeout`	`5m`	Timeout when polling for completion
`--dry-run`	`false`	Validate 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:

Flag	Default	Description
`--format`		Target format, e.g., `mp4`, `webm`, `ogg`
`--size`		Output size, e.g., `640x480`
`--resize-mode`		`preserve_ratio`, `change_ratio`, `scale_crop`, or `add_padding`
`--quality`		`normal`, `better`, `best`, `lighter`, or `lightest`
`--cut`		Time range, e.g., `000:00:05.000/000:00:15.000`
`--thumbs`		Number of thumbnails to generate
`--store`	`false`	Store the converted file
`--no-wait`	`false`	Return conversion token without waiting
`--timeout`	`5m`	Timeout when polling for completion
`--dry-run`	`false`	Validate 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 name	Description
`uc-clamav-virus-scan`	Virus scanning (ClamAV)
`aws-rekognition-detect-labels`	Image labeling (AWS Rekognition)
`aws-rekognition-detect-moderation-labels`	Content moderation (AWS Rekognition)
`remove-bg`	Background 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:

Flag	Default	Description
`--params`		Add-on parameters as JSON
`--no-wait`	`false`	Return request ID without waiting
`--timeout`	`5m`	Timeout when polling for completion
`--dry-run`	`false`	Validate 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:

Flag	Default	Description
`--event`	`file.uploaded`	Event type
`--active`	`true`	Whether the webhook is active
`--signing-secret`		Secret for webhook signature verification
`--dry-run`	`false`	Validate 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:

Flag	Default	Description
`--target-url`		New target URL
`--event`		New event type
`--active`		Whether the webhook is active (`true` or `false`)
`--signing-secret`		New signing secret
`--dry-run`	`false`	Show 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:

Flag	Default	Description
`--dry-run`	`false`	Verify 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

$	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

$	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

$	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

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

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

$	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

$	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

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

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

$	# 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