Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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": "user@acme.com"
    },
    "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": "dev@acme.com"
    }
  }
}

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_CLI_M2M_CLIENT_ID

M2M OAuth client ID for carto auth login --m2m. The --client-id flag takes precedence.

CARTO_CLI_M2M_CLIENT_SECRET

M2M OAuth client secret for carto auth login --m2m. The --client-secret flag takes precedence.

CARTO_API_BASE_URL

API base URL saved by carto auth login --m2m. The --api-base-url flag takes precedence. Default: https://gcp-us-east1.api.carto.com.

CARTO_NO_UPDATE_NOTIFIER

Turn off the update notice. NO_UPDATE_NOTIFIER works too.

Update notice

When a newer version of the CLI is published, each command ends with a short notice that names the new version and the command to install it:

To find new versions, the CLI checks the npm registry at most once a day, in a background process, so your commands never wait for it. The result is stored in ~/.carto/update-check.json. The notice only appears when the CLI runs in an interactive terminal: with --json, with piped output and in CI (when the CI variable is set), the CLI neither checks nor prints anything.

If the npm registry can't be reached, the check fails silently and no notice appears. To turn the check off, set CARTO_NO_UPDATE_NOTIFIER=1, for example when your team installs and upgrades the CLI centrally.

Proxies

The CLI follows the same proxy variables as curl and git. Set HTTPS_PROXY (or HTTP_PROXY) to route requests through a corporate proxy, and list in NO_PROXY the hosts that must be reached directly, such as a Self-Hosted CARTO instance on an internal-only hostname.

Variable
Description

HTTPS_PROXY, HTTP_PROXY

Proxy URL for outgoing requests. HTTPS_PROXY is used when both are set, for http and https targets alike.

NO_PROXY

Comma-separated hosts that bypass the proxy: an exact host (carto.internal.example.com), a domain suffix with a leading dot (.example.com), *.example.com, host:port, or * for everything.

Lowercase names (https_proxy, no_proxy) work too. A bare domain such as example.com only matches that exact host, not its subdomains; use the leading dot form to cover them.

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.

--yes, -y

Skip confirmation prompts. Delete commands (and do unsubscribe) otherwise ask you to type delete to confirm. --json also skips the prompt.

--commands

Print the command catalogue. carto --commands --json prints it in machine-readable form for agents and scripts.

--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

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

Last updated

Was this helpful?