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

# CLI configuration

> Configure authentication, environment variables, config files, and multi-project setups for the Uploadcare CLI.

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:

```yaml
# Top-level keys are used as fallback when no project is selected
public_key: "demopublickey"
secret_key: "demosecretkey"

# Account-level token for project management commands
project_api_token: "your-bearer-token"

# Set a default named project
default_project: "Production"

# Named projects for multi-project setups
projects:
  "Production":
    public_key: "prod-public-key"
    secret_key: "prod-secret-key"
    cdn_base: "https://cdn.example.com"  # optional per-project CDN
  "Staging":
    public_key: "staging-public-key"
    secret_key: "staging-secret-key"

# API base URL overrides (rarely needed)
# rest_api_base: "https://api.uploadcare.com"
# 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.

> **Info**
>
> Project API tokens are not yet available in the dashboard. To get one,
> contact support at [help@uploadcare.com](mailto:help@uploadcare.com).

> **Warning**
>
> **Warning:** 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](https://app.uploadcare.com/projects/-/api-keys/) 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):

```bash
uploadcare project list --project-api-token <token>
```

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

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

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

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