CLIGuides

CLI in CI/CD pipelines

The CLI is designed for automation: structured JSON output, predictable exit codes, environment-variable authentication, and no interactive prompts.

Setup in CI

Install the CLI in a setup step:

$curl -fsSL https://raw.githubusercontent.com/uploadcare/uploadcare-cli/main/scripts/install.sh | sh

Authenticate via environment variables:

Set UPLOADCARE_PUBLIC_KEY and UPLOADCARE_SECRET_KEY in your CI platform’s secret management system.

Never hardcode API keys in pipeline configuration files. Use your platform’s secrets or environment variable management instead.

Exit codes

The CLI uses predictable exit codes so scripts can branch on success or failure:

CodeMeaningExample cause
0SuccessOperation completed
1API or runtime errorFile not found, partial batch failure
2Usage errorInvalid flags, bad UUID format
3Auth or config errorMissing or invalid credentials

Use in shell conditionals:

$if uploadcare file upload build/output.zip --json uuid; then
$  echo "Upload succeeded"
$else
$  echo "Upload failed with exit code $?"
$  exit 1
$fi

Batch operations return exit code 1 for partial failures. The JSON output includes a problems field with per-file error details:

$uploadcare file store UUID1 UUID2 UUID3 --json all
$# Exit code 1 if some UUIDs had errors, 0 if all succeeded

GitHub Actions example

1name: Upload assets to Uploadcare
2on:
3  push:
4    branches: [main]
5
6jobs:
7  upload:
8    runs-on: ubuntu-latest
9    steps:
10      - uses: actions/checkout@v4
11
12      - name: Install Uploadcare CLI
13        run: curl -fsSL https://raw.githubusercontent.com/uploadcare/uploadcare-cli/main/scripts/install.sh | sh
14
15      - name: Build
16        run: npm run build
17
18      - name: Upload build artifacts
19        env:
20          UPLOADCARE_PUBLIC_KEY: ${{ secrets.UPLOADCARE_PUBLIC_KEY }}
21          UPLOADCARE_SECRET_KEY: ${{ secrets.UPLOADCARE_SECRET_KEY }}
22        run: |
23          uploadcare file upload dist/assets/*.js --store true --json uuid,filename

Batch operations

Upload all files in a directory:

$uploadcare file upload ./images/*.jpg --store true --json uuid,filename

Upload file paths from stdin:

$find ./images -name '*.png' | uploadcare file upload --from-stdin --json uuid

Delete all unstored files:

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

Store all temporary files:

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

Preview destructive operations with dry-run:

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

Webhook management during deployment

Register or update webhooks as part of your deployment process:

Create a webhook:

$uploadcare webhook create https://api.example.com/hooks/upload --event file.uploaded

Update a webhook URL on deploy:

$uploadcare webhook update 12345 --target-url https://api-v2.example.com/hooks/upload

List current webhooks:

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

Multi-environment management

Use named projects or the --project flag to target different environments:

$# Deploy to staging
$uploadcare file upload ./assets/* --project "Staging" --store true
$
$# Deploy to production
$uploadcare file upload ./assets/* --project "Production" --store true

In CI, switch environments via the UPLOADCARE_PROJECT variable:

1jobs:
2  deploy-staging:
3    env:
4      UPLOADCARE_PROJECT: "Staging"
5    steps:
6      - run: uploadcare file upload ./assets/*
7
8  deploy-production:
9    env:
10      UPLOADCARE_PROJECT: "Production"
11    steps:
12      - run: uploadcare file upload ./assets/*

See Configuration for setting up named projects.