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

# Convert, add-ons, webhooks, and utilities

> Reference for Uploadcare CLI commands — document/video conversion, add-ons, webhooks, and utility commands.

> **Tip**
>
> **Tip:** Global flags like `--json`, `--jq`, `-v`, and `--quiet` are available on every command.
> See [Configuration](/docs/cli/configuration/#global-flags) 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](/docs/transformations/file-conversion/) and
[Video processing](/docs/transformations/video-encoding/) for details on supported formats.

### convert document

Convert a document to another format.

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

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

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

```bash
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](/docs/security/malware-protection/), [Object recognition](/docs/object-recognition/),
and [Background removal](/docs/remove-bg/) for details.

### addon execute

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

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

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

```bash
uploadcare addon status <addon-name> <request-id>
```

Status values: `in_progress`, `done`, `error`.

**JSON fields:** `status`, `result`

**Examples:**

```bash
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](/docs/webhooks/) for details on event payloads and delivery.

### webhook list

List all webhooks for the current project.

```bash
uploadcare webhook list
```

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

**Examples:**

```bash
uploadcare webhook list
uploadcare webhook list --json all
uploadcare webhook list --json id,target_url,event,is_active
```

### webhook create

Create a new webhook.

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

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

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

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

```bash
uploadcare webhook delete <webhook-id> [flags]
```

**Flags:**

| Flag        | Default | Description             |
| ----------- | ------- | ----------------------- |
| `--dry-run` | `false` | Verify without deleting |

**Examples:**

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

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

```bash
uploadcare api-schema
```

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

```bash
uploadcare version
```

```bash
uploadcare version --json all
```

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

### completion

Generate shell completion scripts for your shell.

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