CLI configuration

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

Configuration priority

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.

Authentication

The CLI uses three authentication modes depending on the operation:

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

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.