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--profileis not specified.profiles— every saved profile keyed by name. Each entry holds:token— bearer token (stored without theBearerprefix).tenant_id— infrastructure region (e.g.gcp-us-east1,onp-acme-prodfor 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.
Authentication priority
The CLI looks for credentials in this order. The first source found wins:
The
--tokenflag on the command line.The
CARTO_API_TOKENenvironment variable.The credentials file (
~/.carto_credentials.json).Legacy config file (
~/.carto/config.json) — for backwards compatibility.
Environment variables
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.
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:
--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?
