CLI

The uploadad CLI wraps the REST API for terminals, scripts, and CI pipelines: upload creatives, track upload jobs, and manage copy variants without writing any HTTP code.

Install

bash

npm install -g uploadad

Or run it without installing:

bash

npx uploadad --help

bun works too: bun install -g uploadad or bunx uploadad.

Authentication

bash

uploadad login

Opens upload.ad in your browser: sign in, approve the device, and you are done. The credential is stored in ~/.config/uploadad/config.json. CLI access requires a paid plan.

For headless environments, authenticate with an API key instead (create one at upload.ad/dashboard/settings/api-keys): run uploadad login --key ua_live_..., or uploadad login --key to be prompted for it.

Every command resolves the credential in this order:

The --api-key flag
The UPLOADAD_API_KEY environment variable
The config file written by uploadad login

For CI, set UPLOADAD_API_KEY as a secret and skip login entirely. To verify which account you are authenticated as, or to sign out:

bash

uploadad whoami   # show the authenticated account
uploadad logout   # sign out and remove stored credentials

Uploading creatives

Pass one or more file paths. Each file becomes its own upload job:

bash

uploadad upload banner.png promo.mp4

Uploads process in the background and the command returns immediately with the job ids. Add --wait to block until every file is completed or failed, which is usually what you want in scripts:

bash

uploadad upload banner.png promo.mp4 --wait

The same limits apply as in the API: up to 25 files per invocation, images up to 30 MB, videos up to 200 MB.

Managing upload jobs

bash

uploadad uploads list                    # newest first, default 100
uploadad uploads list --limit 20
uploadad uploads list --status failed    # processing, completed, or failed
uploadad uploads retry <id>              # re-run a failed upload
uploadad uploads rm <id>                 # dismiss a completed or failed job

Managing creatives

bash

uploadad creatives list
uploadad creatives rm <id> [<id> ...]

Managing copy variants

bash

uploadad copy list <creativeId>

# Create a variant
uploadad copy add <creativeId> \
  --headline "Summer sale" \
  --primary-text "Save 20% this week only." \
  --description "Limited time offer" \
  --label "variant-a"

# Update an existing variant
uploadad copy add <creativeId> --id <copyId> --headline "Summer sale, extended"

# Delete a variant
uploadad copy rm <creativeId> <copyId>

Scripting

The read commands (whoami, uploads list, creatives list, and copy list) accept a --json flag that prints the raw API response instead of the table output, ready for jq:

bash

uploadad uploads list --json | jq -r '.uploads[] | select(.status == "failed") | .id'

Filters like --status still apply to the JSON output.

Global flags

Flag	Description
`--api-key <key>`	API key, overrides the environment variable and config file
`--base-url <url>`	API base URL, default `https://upload.ad`

UPLOADAD_BASE_URL also overrides the base URL when set.

MCP server

The CLI ships the upload.ad MCP server for AI agents:

bash

uploadad mcp

See the MCP setup guide for connecting it to Claude Code, Claude Desktop, or Cursor.