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

```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: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.