Configuration

Credentials file

The CLI stores authentication credentials in ~/.carto_credentials.json with support for multiple profiles:

{
  "current_profile": "production",
  "profiles": {
    "production": {
      "token": "your-bearer-token",
      "tenant_id": "gcp-us-east1",
      "tenant_domain": "carto.acme.com",
      "organization_id": "ac_yv1im1y2",
      "organization_name": "carto-prod",
      "user_email": "[email protected]"
    },
    "staging": {
      "token": "staging-bearer-token",
      "tenant_id": "gcp-us-east1",
      "tenant_domain": "carto-dev.acme.com",
      "organization_id": "ac_7p1sk0gs",
      "organization_name": "Carto-Dev",
      "user_email": "[email protected]"
    }
  }
}

Structure:

• current_profile — the default profile used when --profile is not specified.

• profiles — every saved profile keyed by name. Each entry holds:

  • token — bearer token (stored without the Bearer prefix).

  • tenant_id — infrastructure region (e.g. gcp-us-east1, onp-acme-prod for a self-hosted tenant).

  • tenant_domain — organization domain (e.g. carto.acme.com).

  • organization_id — account ID (e.g. ac_yv1im1y2).

  • organization_name — human-readable organization name.

  • user_email — authenticated user email.

The API base URL is automatically constructed as https://{tenant_id}.api.carto.com.

Old-format credentials files (single profile at the root level) are automatically migrated to this nested structure on first use.

Authentication priority

The CLI looks for credentials in this order. The first source found wins:

1. The --token flag on the command line.

2. The CARTO_API_TOKEN environment variable.

3. The credentials file (~/.carto_credentials.json).

4. Legacy config file (~/.carto/config.json) — for backwards compatibility.

Environment variables

Variable	Description
CARTO_API_TOKEN	API token for authentication. Overrides the credentials file.
CARTO_PROFILE	Profile to use. Overrides current_profile from the credentials file.
CARTO_AUTH_ENV	Auth environment. Only set if instructed by support.
CARTO_AUTH_PORT	Callback server port for the OAuth login flow. Default: 3003.

Global flags

These flags work with every command:

Flag	Description
--json	Output in JSON format. Use for scripting and agent tool use.
--debug	Show request details (method, URL, headers, body). Tokens are masked.
--token <token>	Override the API token for this command.
--base-url <url>	Override the base API URL.
--profile <name>	Use a specific profile (default: the current_profile value).
--version, -v	Show version.
--help, -h	Show help.

Debugging requests

# Show full request details for any command
carto --debug maps list

# Combine with --json for clean output + visible request internals
carto --debug --json auth status

Debug output includes the HTTP method, full URL, request headers (with the token masked), and the request body for POST / PATCH requests.

Using environment variables

# Authenticate via env var (useful in CI/CD)
export CARTO_API_TOKEN="eyJhbGc..."
carto maps list

# Override with CLI flags
carto --token "different-token" --base-url "https://eu-west1.api.carto.com" maps list