---

name: carto-cli description: Complete carto CLI reference commands - load me before any carto command

CARTO CLI Reference

The carto CLI is the command-line interface for the CARTO platform. This skill provides comprehensive documentation for the most commonly used commands.

Version: 0.1.0

---

Global Options

These flags work with all commands:

Environment Variables:

• CARTO_API_TOKEN - API token for authentication
• CARTO_PROFILE - Profile to use (overrides current_profile)

---

Authentication Commands

carto auth status

Check authentication status and token expiration.

Copycarto auth status [profile]

Output includes:

• Token validity and expiration time
• Tenant, organization, and user info
• Available profiles

Example:

Copycarto auth status
# Shows: ✓ Authenticated, token expires in X hours

carto auth login

Interactive browser-based login.

Copycarto auth login [profile]
  --organization-name <name>  # Required for SSO login
  --env <env>                 # Only if instructed by support

Important: Opens a browser window. Inform the user before running.

Examples:

Copycarto auth login                              # Default login
carto auth login production                   # Login with profile name
carto auth login --organization-name "ACME"   # SSO login

carto auth logout

Remove stored credentials.

Copycarto auth logout [profile]

carto auth use

Switch between profiles.

Copycarto auth use <profile>

carto auth whoami

Show current user info only.

Copycarto auth whoami

---

Connection Commands

carto connections list

List all available connections.

Copycarto connections list [--all]
  --page <n>          # Page number (default: 1)
  --page-size <n>     # Items per page (default: 10)
  --search <query>    # Search by text
  --json              # JSON output

Examples:

Copycarto connections list                    # First 10 connections
carto connections list --all              # All connections (paginated)
carto connections list --search bigquery  # Search by name
carto connections list --json             # JSON output for parsing

carto connections get

Get detailed connection info by ID.

Copycarto connections get <id>

carto connections browse

Browse connection resources hierarchically.

Copycarto connections browse <name> [path]
  --page <n>          # Page number (default: 1)
  --page-size <n>     # Items per page (default: 30)

Path hierarchy for BigQuery:

1. No path: Lists projects
2. "project": Lists datasets
3. "project.dataset": Lists tables

Examples:

Copycarto connections browse carto_dw                          # List projects
carto connections browse carto_dw "carto-demo-data"        # List datasets
carto connections browse carto_dw "carto-demo-data.demo_tables"  # List tables

Gotcha: Path must be quoted if it contains dots.

carto connections describe

Get table schema and details.

Copycarto connections describe <name> "<table-path>"
  --json              # JSON output (recommended)

Examples:

Copycarto connections describe carto_dw "carto-demo-data.demo_tables.cities"
carto connections describe my-bq "project.dataset.table" --json

Gotcha: Table path must be quoted and use fully-qualified name.

---

SQL Commands

carto sql query

Run SQL query and return results.

Copycarto sql query <connection> [sql]
  --file <path>       # Read SQL from file
  --cache             # Use cached results (1yr cache, 1min timeout)
  --json              # JSON output

Input methods (in priority order):

1. Inline SQL argument
2. --file flag
3. Stdin (pipe)

Examples:

Copy# Inline query
carto sql query carto_dw "SELECT * FROM dataset.table LIMIT 10"

# From file
carto sql query carto_dw --file query.sql

# From stdin
echo "SELECT COUNT(*) FROM dataset.table" | carto sql query carto_dw

# With caching
carto sql query carto_dw "SELECT * FROM table" --cache

# JSON output
carto sql query carto_dw "SELECT * FROM table LIMIT 5" --json

JSON output format:

Copy{
  "rows": [{"column": "value"}],
  "schema": [{"name": "column", "type": "string"}],
  "meta": {"cacheHit": false, "totalBytesProcessed": "1234"}
}

Gotcha: Default POST (no cache). Use --cache for GET with caching.

carto sql job

Run SQL job for DDL/DML operations (no results returned).

Copycarto sql job <connection> [sql]
  --file <path>       # Read SQL from file

Use for:

• CREATE TABLE
• INSERT/UPDATE/DELETE
• Any long-running operation

Examples:

Copycarto sql job carto_dw "CREATE TABLE dataset.newtable AS SELECT..."
carto sql job carto_dw --file create_tables.sql
cat workflow.sql | carto sql job carto_dw

Behavior: Polls until job completes, no timeout.

---

Workflow Commands

carto workflows list

List workflows in the organization.

Copycarto workflows list [options]
  --page <n>              # Page number
  --pageSize <n>          # Items per page
  --orderBy <field>       # Order by field
  --orderDirection <dir>  # ASC or DESC
  --search <term>         # Search term
  --privacy <level>       # Privacy level
  --tags <json-array>     # Filter by tags
  --json                  # JSON output

Examples:

Copycarto workflows list --pageSize 10
carto workflows list --search "sales" --json
carto workflows list --orderBy updatedAt --orderDirection DESC

carto workflows get

Get workflow details.

Copycarto workflows get <id> [--json]

carto workflows validate

Validate a workflow diagram JSON file.

Copycarto workflows validate <file>
  --connection <name>       # Connection for schema validation (recommended)
  --temp-location <loc>     # Temp location (e.g., project.dataset)
  --json                    # JSON output

Important: Without --connection, only structure is validated, NOT column types or table existence.

Examples:

Copy# Structure-only validation (basic)
carto workflows validate workflow.json

# Full validation with connection (recommended)
carto workflows validate workflow.json \
  --connection my-bigquery \
  --temp-location "project.dataset" \
  --json

carto workflows to-sql

Generate SQL from workflow diagram.

Copycarto workflows to-sql <file>
  --temp-location <loc>     # Where intermediate tables are created
  --provider <name>         # Override diagram provider
  --dry-run                 # Generate empty tables for schema validation
  --no-cache                # Disable caching

Gotcha: Does NOT support --connection flag. This is different from validate.

Examples:

Copy# Generate SQL
carto workflows to-sql workflow.json --temp-location "project.dataset"

# Dry-run for schema validation
carto workflows to-sql workflow.json --dry-run

# Save to file and execute
carto workflows to-sql workflow.json --temp-location "project.dataset" > workflow.sql
cat workflow.sql | carto sql job my-connection

carto workflows show

Display workflow diagram structure (for debugging).

Copycarto workflows show <file>

carto workflows components list

List available workflow components.

Copycarto workflows components list
  --connection <name>       # Connection name (required)
  --json                    # JSON output (recommended)

Example:

Copycarto workflows components list --connection my-bigquery --json

Gotcha: Requires --connection. There is no --provider flag for listing.

carto workflows components get

Get detailed component definitions.

Copycarto workflows components get <names>
  --connection <name>       # Connection name (required)
  --json                    # JSON output (always use this)

Examples:

Copy# Single component
carto workflows components get native.buffer --connection my-bq --json

# Multiple components
carto workflows components get native.buffer,native.spatialjoin --connection my-bq --json

JSON output includes: inputs, outputs, types, defaults, validation rules.

carto workflows schedule

Manage workflow schedules.

Copy# Add schedule
carto workflows schedule add <id>
  --expression <expr>       # Schedule expression (required)
  --connection <name>       # Connection name (optional)

# Update schedule
carto workflows schedule update <id>
  --expression <expr>       # New expression (required)

# Remove schedule
carto workflows schedule remove <id>

Schedule expression formats by provider:

carto workflows copy

Copy workflow between profiles/organizations.

Copycarto workflows copy <id>
  --dest-profile <profile>   # Destination profile (required)
  --source-profile <profile> # Source profile (default: current)
  --connection <name>        # Destination connection (optional)
  --title <title>            # Override title (optional)
  --skip-source-validation   # Skip table accessibility check

---

Import Commands

carto imports create

Import geospatial files to a table.

Copycarto imports create
  --file <path>             # Local file to upload
  --url <url>               # Remote file URL
  --connection <name>       # Connection name (required)
  --destination <fqn>       # Target table FQN (required)
  --overwrite               # Overwrite existing table
  --no-autoguessing         # Disable column type detection
  --async                   # Return immediately (don't wait)

Supported formats: CSV, GeoJSON, GeoPackage, GeoParquet, KML, KMZ, Shapefile (zip)

Size limit: 1GB per file

Examples:

Copy# Local file
carto imports create \
  --file ./data.csv \
  --connection carto_dw \
  --destination project.dataset.table

# Remote URL
carto imports create \
  --url https://example.com/data.geojson \
  --connection carto_dw \
  --destination project.dataset.my_data

# Overwrite existing
carto imports create \
  --file ./updated.csv \
  --connection carto_dw \
  --destination project.dataset.table \
  --overwrite

Behavior: Waits for completion by default. Use --async to return immediately.

---

Common Gotchas

---

Quick Reference