CLI configuration | Uploadcare docs

The CLI reads configuration from three sources. When the same setting appears in multiple sources, the highest-priority source wins.

Configuration priority

Priority	Source	Example
1 (highest)	CLI flags	`--public-key demopublickey`
2	Environment variables	`UPLOADCARE_PUBLIC_KEY=demopublickey`
3	Named project (`--project` flag or `UPLOADCARE_PROJECT` env)	`--project "My App"`
4	Default project from config file	`default_project: "My App"`
5 (lowest)	Top-level keys in config file	`public_key: demopublickey`

Config file

The CLI looks for a config file at ~/.uploadcare/config.yaml. Here is a full example:

1 # Top-level keys are used as fallback when no project is selected
2 public_key: "demopublickey"
3 secret_key: "demosecretkey"
4 
5 # Account-level token for project management commands
6 project_api_token: "your-bearer-token"
7 
8 # Set a default named project
9 default_project: "Production"
10 
11 # Named projects for multi-project setups
12 projects:
13   "Production":
14     public_key: "prod-public-key"
15     secret_key: "prod-secret-key"
16     cdn_base: "https://cdn.example.com"  # optional per-project CDN
17   "Staging":
18     public_key: "staging-public-key"
19     secret_key: "staging-secret-key"
20 
21 # API base URL overrides (rarely needed)
22 # rest_api_base: "https://api.uploadcare.com"
23 # upload_api_base: "https://upload.uploadcare.com"

Environment variables

Environment variables are the recommended way to authenticate in CI/CD and containerized environments.

Variable	Description
`UPLOADCARE_PUBLIC_KEY`	API public key
`UPLOADCARE_SECRET_KEY`	API secret key
`UPLOADCARE_PROJECT_API_TOKEN`	Account-level bearer token for project management (see below)
`UPLOADCARE_PROJECT`	Named project to use from config file
`UPLOADCARE_VERBOSE`	Enable verbose HTTP logging (`1` or `true`)
`UPLOADCARE_REST_API_BASE`	Override REST API base URL
`UPLOADCARE_UPLOAD_API_BASE`	Override Upload API base URL
`UPLOADCARE_CDN_BASE`	Override CDN base URL
`UPLOADCARE_PROJECT_API_BASE`	Override Project API base URL
`NO_COLOR`	Disable colored output (any value)

Authentication

The CLI uses three authentication modes depending on the operation:

Auth mode	Required credentials	Used by
REST API (HMAC)	Public key + secret key	File, metadata, group, webhook, convert, and add-on commands
Upload API	Public key only	`file upload`, `file upload-from-url`
Project API (bearer)	Project API token	`project list`, `project create`, `project update`, `project delete`, `project secret`, `project usage`

project info uses the REST API when called without arguments, or the Project API when a project argument is given.

Project API tokens are not yet available in the dashboard. To get one, contact support at help@uploadcare.com.

Never commit API keys to version control. Use environment variables or a config file outside your repository. In CI/CD, store keys in your platform’s secret management system.

Get your API keys from the API keys page in the dashboard.

Multi-project setup

Manage multiple Uploadcare projects from one machine by defining named projects in your config file.

List available projects (requires a Project API token):

$ uploadcare project list --project-api-token <token>

Add a project to your config and set it as default:

$ uploadcare project use <pub-key> --create-secret --use

This creates a new API secret for the project, saves credentials to ~/.uploadcare/config.yaml, and sets it as the default.

Switch between projects per command:

$ # Use a named project for a single command
$ uploadcare file list --project "Staging"
$ 
$ # Or set via environment variable
$ export UPLOADCARE_PROJECT="Staging"
$ uploadcare file list

Example: staging vs. production workflow:

$ # Upload to staging
$ uploadcare file upload assets/*.jpg --project "Staging"
$ 
$ # Verify, then upload to production
$ uploadcare file upload assets/*.jpg --project "Production"

Global flags

These flags are available on every command.

Flag	Description
`--public-key`	API public key
`--secret-key`	API secret key
`--project-api-token`	Account-level bearer token
`--project <name>`	Use a named project from config
`--json <fields>`	Output as JSON. `all` for every field, or `field1,field2` to select specific fields
`--jq <expr>`	Apply a jq expression to JSON output (implies `--json`)
`-q, --quiet`	Suppress all non-error output
`-v, --verbose`	Print HTTP request/response details to stderr
`--no-color`	Disable colored output
`--rest-api-base`	Override REST API base URL
`--upload-api-base`	Override Upload API base URL
`--cdn-base`	Override CDN base URL
`--project-api-base`	Override Project API base URL