> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/cli/configuration.md).

# Configuration

## Credentials file

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

```json
{
  "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`.

{% hint style="info" %}
Old-format credentials files (single profile at the root level) are automatically migrated to this nested structure on first use.
{% endhint %}

## 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](#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:

```
A new version of the CARTO CLI is available: 0.14.0 → 0.15.0
To update, run: npm install -g @carto/carto-cli
```

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.

```bash
# Self-Hosted instance on an internal hostname, behind a corporate proxy
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY=".example.com,localhost,127.0.0.1"
carto projects list
```

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

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.carto.com/carto-for-agents/cli/configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
