CARTO CLI

Command-line interface for managing CARTO platform resources. Manage maps, workflows, connections, users, and more through the CARTO API.

Installation

npm install -g @carto/carto-cli

Optional: SQL Querying of Activity Data

For the carto activity query command, install DuckDB:

npm install duckdb

CARTO Platform version support

The CARTO CLI is designed to work with versions 2026.1.7 and above of the CARTO Self-hosted platform.

Latest version of the CARTO CLI will always work with the up-to-date version of the CARTO SaaS platform.

Quick Start

# 1. Login to CARTO (opens browser)
carto auth login

# 2. List your maps
carto maps list

# 3. Get help
carto --help

Command Reference

Global Options

| Option | Description | |--------|-------------| | --json | Output in JSON format | | --debug | Show request details (method, URL, headers) | | --yes, -y | Skip confirmation prompts | | --token <token> | Override API token | | --base-url <url> | Override base API URL | | --profile <name> | Use specific profile | | --version, -v | Show version | | --help, -h | Show help |

Environment Variables

| Variable | Description | |----------|-------------| | CARTO_API_TOKEN | API token for authentication | | CARTO_PROFILE | Profile to use (overrides credentials file) | | CARTO_AUTH_ENV | Auth environment (only set if instructed by support) | | CARTO_AUTH_PORT | Callback server port for login (default: 3003) |

auth

Manage authentication and profiles.

carto auth login [profile]              # Browser-based OAuth login
carto auth logout [profile]             # Remove stored credentials
carto auth status [profile]             # Show authentication status
carto auth use <profile>                # Switch default profile
carto auth whoami                       # Show current user info

Options for auth login:

| Option | Description | |--------|-------------| | --organization-name <name> | Organization name for SSO login | | --organization-id <id> | Organization ID for SSO login | | --no-launch-browser | Manual URL mode for headless environments | | --env <environment> | Auth environment (only if instructed by support) |

Examples:

# Login to default profile
carto auth login

# Login to named profile with SSO
carto auth login production --organization-name "ACME Corp"

# Headless login (SSH, containers)
carto auth login --no-launch-browser

# Switch profiles
carto auth use staging

credentials

Manage API tokens and OAuth clients for applications.

carto credentials list [type]                    # List credentials (tokens|spa|m2m)
carto credentials create token [options]         # Create API token
carto credentials create spa [options]           # Create SPA OAuth client
carto credentials create m2m [options]           # Create M2M OAuth client
carto credentials get <type> <id>                # Get credential details
carto credentials update <type> <id> [options]   # Update credential
carto credentials delete <type> <id>             # Delete credential

API Token Options:

| Option | Description | |--------|-------------| | --connection <name> | Connection name for grants | | --source <pattern> | Table/tileset source pattern (e.g., "demo_tables.*") | | --apis <list> | Comma-separated APIs (sql, maps, imports, lds) | | --referer <url> | Allowed referer URL |

SPA OAuth Client Options:

| Option | Description | |--------|-------------| | --title <name> | Application title (required) | | --callback <url> | OAuth callback URL | | --logout-url <url> | Logout redirect URL | | --web-origin <url> | Web origin URL | | --allowed-origin <url> | Allowed CORS origin |

M2M OAuth Client Options:

| Option | Description | |--------|-------------| | --title <name> | Application title (required) |

Examples:

# Create API token
carto credentials create token \
  --connection carto_dw \
  --source "demo_tables.*" \
  --apis sql,maps

# Create SPA OAuth client
carto credentials create spa \
  --title "My Dashboard" \
  --callback "https://myapp.com/callback"

# Create M2M OAuth client
carto credentials create m2m --title "ETL Service"

maps

Manage maps.

carto maps list [options]                        # List maps
carto maps get <map-id>                          # Get map details
carto maps delete <map-id>                       # Delete map
carto maps copy <map-id> --dest-profile <name>   # Copy map between profiles

List Options:

| Option | Description | |--------|-------------| | --page <n> | Page number | | --page-size <n> | Items per page | | --search <term> | Search filter | | --privacy <level> | Filter by privacy (public, shared, private) | | --mine | Show only your maps | | --all | Fetch all pages |

Copy Options:

| Option | Description | |--------|-------------| | --dest-profile <name> | Destination profile (required) | | --source-profile <name> | Source profile (default: current) | | --connection-mapping <map> | Map connections (e.g., "src=dest,src2=dest2") | | --title <title> | Override title | | --keep-privacy | Preserve privacy setting | | --skip-source-validation | Skip table accessibility checks |

Examples:

# List maps with search
carto maps list --search "dashboard" --mine

# Copy map to production
carto maps copy abc123 --dest-profile production

# Copy with connection mapping
carto maps copy abc123 --dest-profile prod \
  --connection-mapping "dev-bq=prod-bq"

workflows

Manage workflows.

carto workflows list [options]                     # List workflows
carto workflows get <id>                           # Get workflow details
carto workflows update <id> <json>                 # Update workflow
carto workflows delete <id>                        # Delete workflow
carto workflows copy <id> --dest-profile <name>    # Copy workflow

List Options:

| Option | Description | |--------|-------------| | --page <n> | Page number | | --pageSize <n> | Items per page | | --orderBy <field> | Order by field | | --orderDirection <dir> | ASC or DESC | | --search <term> | Search filter | | --privacy <level> | Filter by privacy | | --tags <json> | Filter by tags (JSON array) |

Copy Options:

| Option | Description | |--------|-------------| | --dest-profile <name> | Destination profile (required) | | --source-profile <name> | Source profile | | --connection <name> | Destination connection | | --title <title> | Override title | | --skip-source-validation | Skip table checks |

Examples:

# List workflows
carto workflows list --search "ETL" --orderBy updated_at

# Copy workflow to production
carto workflows copy abc123 --dest-profile production

connections

Manage data warehouse connections.

carto connections list                   # List connections
carto connections get <id>               # Get connection details
carto connections create <json>          # Create connection
carto connections update <id> <json>     # Update connection
carto connections delete <id>            # Delete connection

Examples:

# List connections
carto connections list

# Create Snowflake connection
carto connections create '{"name":"my-snowflake","type":"snowflake","parameters":{"account":"myaccount"}}'

imports

Import geospatial files into your data warehouse.

Supported: CSV, GeoJSON, GeoPackage, GeoParquet, KML, KMZ, Shapefile (zip) Size Limit: 1GB per file

carto imports create --file <path> --connection <name> --destination <table>
carto imports create --url <url> --connection <name> --destination <table>

Options:

| Option | Description | |--------|-------------| | --file <path> | Local file to upload | | --url <url> | Remote file URL | | --connection <name> | Connection name (required) | | --destination <fqn> | Fully qualified table name (required) | | --overwrite | Overwrite existing table | | --no-autoguessing | Disable column type detection | | --async | Return immediately without waiting |

Examples:

# Import local file
carto imports create \
  --file ./data.csv \
  --connection carto_dw \
  --destination project.dataset.my_table

# Import from URL with overwrite
carto imports create \
  --url https://example.com/data.geojson \
  --connection carto_dw \
  --destination project.dataset.table \
  --overwrite

sql

Run SQL queries on your data warehouse.

carto sql query <connection> "<sql>"     # Run query (returns results)
carto sql job <connection> "<sql>"       # Run DDL/DML (no results)

Options:

| Option | Description | |--------|-------------| | --file <path> | Read SQL from file | | --cache | Use cached GET request (query only) |

Input methods: Command argument, --file, or stdin.

Examples:

# Run query
carto sql query myconn "SELECT * FROM dataset.table LIMIT 10"

# Run from file
carto sql query myconn --file query.sql

# Run DDL job
carto sql job myconn "CREATE TABLE dataset.new AS SELECT * FROM dataset.old"

# Pipe from stdin
echo "SELECT COUNT(*) FROM table" | carto sql query myconn

org

View organization statistics.

carto org stats                # Show organization stats and quotas

Shows: users, resources, usage quotas, AI quotas (based on permissions).

users

Manage organization users and invitations.

carto users list [options]               # List users
carto users get <user-id|email>          # Get user details
carto users invite <emails> --role <role>  # Invite users
carto users invitations                  # List pending invitations

List Options:

| Option | Description | |--------|-------------| | --page <n> | Page number | | --page-size <n> | Items per page | | --role <role> | Filter by role | | --search <term> | Search filter | | --all | Fetch all pages |

Roles: Builder, Viewer, Guest

Examples:

# List builders
carto users list --role Builder

# Invite users
carto users invite [email protected] --role Builder

# Invite multiple users
carto users invite [email protected],[email protected] --role Viewer

activity

Query and export activity data (Enterprise Large+).

carto activity query --start-date <date> --end-date <date> --sql "<sql>"
carto activity export --start-date <date> --end-date <date> [options]

Query Options:

| Option | Description | |--------|-------------| | --start-date <date> | Start date (YYYY-MM-DD) | | --end-date <date> | End date (YYYY-MM-DD) | | --sql <query> | DuckDB SQL query | | --no-cache | Force fresh download |

Export Options:

| Option | Description | |--------|-------------| | --category <name> | Export specific category | | --format <type> | Output format (csv, parquet) | | --output-dir <path> | Output directory |

Available Tables: activity, apiUsage, userList, groupList

Examples:

# Count events
carto activity query \
  --start-date 2025-01-01 --end-date 2025-01-07 \
  --sql "SELECT COUNT(*) FROM activity"

# Export to parquet
carto activity export \
  --start-date 2025-01-01 --end-date 2025-01-07 \
  --format parquet

aifeature

Interact with AI agents in maps.

carto aifeature aiagent <map-id> [message]   # Chat with map agent

Options:

| Option | Description | |--------|-------------| | --conversation-id <id> | Continue previous conversation | | --file <path> | Read message from file |

Examples:

# Interactive chat
carto aifeature aiagent abc123

# One-shot message
carto aifeature aiagent abc123 "What are the traffic patterns?"

# JSON output
carto aifeature aiagent abc123 "Summarize" --json

aiproxy

Access CARTO's LLM infrastructure (OpenAI-compatible).

carto aiproxy info                         # Show connection info
carto aiproxy models                       # List available models
carto aiproxy chat "<message>" --model <name>  # Chat with LLM

Chat Options:

| Option | Description | |--------|-------------| | --model <name> | Model to use (required) | | --system <text> | System prompt | | --temperature <n> | Sampling temperature (0-2) | | --max-tokens <n> | Maximum tokens | | --file <path> | Read message from file |

Examples:

# List models
carto aiproxy models

# Simple chat
carto aiproxy chat "What is 2+2?" --model gpt-4

# With system prompt
carto aiproxy chat "Analyze this data" \
  --model gemini-2.5-flash \
  --system "You are a data analyst"

admin

Superadmin operations for organization management.

carto admin list <resource-type>           # List all resources (maps|workflows|connections)
carto admin batch-delete <json>            # Batch delete resources
carto admin transfer <json>                # Transfer resources between users

Examples:

# List all maps
carto admin list maps --page-size 50

# Batch delete
carto admin batch-delete '{"resource_ids":["map1","map2"]}'

# Transfer resources
carto admin transfer '{"from_user":"[email protected]","to_user":"[email protected]","resource_ids":["map1"]}'

Configuration

Credentials File

Credentials are stored in ~/.carto_credentials.json:

{
  "current_profile": "production",
  "profiles": {
    "production": {
      "token": "eyJhbGc...",
      "tenant_id": "gcp-us-east1",
      "tenant_domain": "myorg.app.carto.com",
      "organization_id": "ac_abc123",
      "organization_name": "my-org",
      "user_email": "[email protected]"
    }
  }
}

Authentication Priority

1. --token flag
2. CARTO_API_TOKEN environment variable
3. Credentials file (~/.carto_credentials.json)

Multiple Profiles

# Login to different profiles
carto auth login staging
carto auth login production

# Switch default profile
carto auth use production

# Use specific profile with any command
carto --profile staging maps list

License

Proprietary - See LICENSE for details.

This software requires a valid CARTO account. Usage is subject to CARTO's Terms of Service.