maps

Manage CARTO Builder maps. Create, edit, validate, publish, copy across organizations, screenshot, and inspect the agent surface.

carto maps list [options]                        # List maps
carto maps get <map-id>                          # Pretty details; --json emits round-trippable JSON
carto maps create [json]                         # Create from JSON (positional, path, or stdin)
carto maps update <map-id> [json]                # Update (partial JSON OK)
carto maps validate [json]                       # Tier-1 preflight (offline, no API calls)
carto maps verify-remote [json]                  # Tier-0 + Tier-2 (validate + warehouse dry-runs)
carto maps publish <map-id>                      # Freeze a snapshot so viewers see current state
carto maps schema [section]                      # JSON Schema reference for agents
carto maps agents <subcommand>                   # AI agent introspection (see below)
carto maps datasets update <map-id> <dataset-id> # PATCH a single dataset on an existing map
carto maps screenshot <map-id> [options]         # Save a PNG screenshot (opt-in Chromium)
carto maps copy <map-id> --dest-profile <name>   # Duplicate (cross-org or same org)
carto maps delete <map-id>                       # Delete map

The bundle model

maps get <id> --json returns a round-trippable bundle — the same shape that maps create and maps update accept. Server-computed fields are stripped, privacy is synthesised from top-level fields, and datasets are inlined. You can pipe the output straight back in:

carto maps get abc123 --json > map.json
jq '.title = "New title"' map.json | carto maps update abc123

Bundle input accepts a positional JSON string, a filesystem path, or stdin:

carto maps create '{"title":"…", "connectionId":"…"}'   # Inline JSON
carto maps create ./map.json                            # Path
carto maps create < map.json                            # Stdin

Pre-flight validation (Tier-1 schema checks, source SQL dry-run, privacy coercion, agent model auto-fill, aggregationExp auto-fill for spatial-index datasets on supported providers) runs before any write — broken bundles reject without creating an orphan map. Post-write verification surfaces as warnings in the JSON output.

For the full bundle recipe (including authoring patterns and the agent skill that drives it), see the carto-create-builder-maps skill.

Two-version model

Private editing mutates the live map via PATCH /maps/:id. Shared and public viewers read from a frozen snapshot created by POST /maps/:id/publish. Setting privacy=shared or privacy=public puts the map in dashboards, but viewers see the prior snapshot (or nothing if never published). Use carto maps publish <id> to update the snapshot — or pass --publish to maps update to chain both.

create and update emit an UNPUBLISHED_SHARED_MAP warning when privacy is shared/public but no snapshot exists.

carto maps list

Option	Description
--mine	Show only your maps.
--search <term>	Free-text search across title/description.
--privacy <level>	Filter by privacy: private, shared, public.
--tags <json>	Filter by tags (JSON array, e.g. '["demo","poc"]').
--order-by <field>	Sort by updatedAt, createdAt, title.
--order-direction <dir>	ASC or DESC.
--page <n> / --page-size <n>	Pagination.
--all	Fetch all pages automatically.

carto maps create / carto maps update

Option	Description
--dry-run	(update) Print planned actions without writing.
--datasets-mode replace	(update) Delete datasets not mentioned in the input (default: merge).
--publish	(update) Chain maps publish <id> after the update succeeds.
--allow-kepler-replace	Allow wholesale keplerMapConfig partial-update replacement (use the read-modify-write cycle instead unless you know what you're doing).

The response includes builderUrl, viewerUrl, and publicUrl as first-class fields. mapUrl is kept as a back-compat alias for builderUrl and will be dropped on the next major.

carto maps validate / carto maps verify-remote

• maps validate — Tier-1 only, offline, no API calls. Same input surface as create. Exits 1 on any issue. Use to iterate on a bundle before writing.

• maps verify-remote — Tier-1 + Tier-2 (warehouse-side checks: source dry-runs, region match, region-aware SQL). Reads credentials but never calls POST /maps. Useful before shipping a bundle in CI.

carto maps publish

Freeze a snapshot so shared/public viewers see the current state:

carto maps publish abc123
# Or chain it onto an update:
carto maps update abc123 < map.json --publish

Snapshots are versioned; the platform tracks lastPublishedAt per map. Republishing replaces the prior snapshot.

carto maps schema [section]

JSON Schema reference for agents authoring bundles. Sections include bundle, dataset, layer.tileset, layer.h3, layer.quadbin, layer.heatmapTile, layer.clusterTile, layer.raster, widgets, sqlparameters, popupsettings, privacy, agent, enums, mapstate, mapstyle, mapsettings, uistate, legendsettings.

carto maps schema layer.h3
carto maps schema uistate

Scale-with-zoom-level radius (tileset point layers): maps schema layer.tileset includes four optional visConfig fields enabling Builder's third Radius mode — alongside Fixed and a column field:

maps validate rejects two shapes that would silently break in Builder: radiusScaleWithZoom: true without a radius value (renders zero-pixel points at the reference zoom), and radiusScaleWithZoom: true alongside a radiusField (mutually exclusive Radius modes).

Field	Type	Notes
radiusScaleWithZoom	boolean	Enables the mode.
radiusReferenceZoom	number (0–22)	Zoom level at which radius is rendered 1:1.
sizeMinPixels	number (1–100)	Lower clamp as the user zooms out.
sizeMaxPixels	number (1–100)	Upper clamp as the user zooms in.

carto maps agents

Discover the AI surface available on the current tenant:

carto maps agents status       # Is CARTO AI enabled? What's the default model?
carto maps agents models       # AI models you can put in agent.config.model (formatted "{source}::{provider}::{model}")
carto maps agents mcp-tools    # MCP tools (workflow-backed) available for agent.config.tools[]
carto maps agents core-tools   # Hardcoded core Builder tools and their activation rules

Call maps agents status before emitting an agent block in a bundle — bundles authored for tenants with CARTO AI disabled get the agent block stripped with a warning.

carto maps datasets update

PATCH a single dataset on an existing map without re-emitting the full bundle. Used to swap the SQL, columns, or aggregation of one source while leaving the rest of the map alone.

carto maps datasets update <map-id> <dataset-id> '{"source":"SELECT … FROM new_table"}'

carto maps copy

Duplicate a map between profiles (organizations). Connections are mapped automatically by name; supply explicit mappings for renamed cases.

# Auto-map connections by name (default)
carto maps copy <map-id> --dest-profile production

# Manual mapping for renamed connections
carto maps copy <map-id> --dest-profile prod \
  --connection-mapping "dev-bq=prod-bq,dev-sf=prod-sf"

# Override source profile and title
carto maps copy <map-id> --source-profile staging --dest-profile prod \
  --title "Production Map"

Option	Description
--dest-profile <name>	(Required) Destination profile name.
--source-profile <name>	Source profile (default: current).
--connection-mapping <map>	Per-source map (e.g. "src1=dst1,src2=dst2"). Preferred for multi-connection maps.
--connection <name>	Legacy: single connection for all datasets.
--title <title>	Override the map title in the destination.
--skip-source-validation	Skip validating that destination connections can read source tables/queries.
--keep-privacy	Preserve privacy setting from source (default: true).

For a full walkthrough including connection-mapping scenarios and troubleshooting, see Examples → Copying maps and workflows between organizations.

carto maps screenshot

carto maps screenshot is experimental. Its flags, render engines, and output may change in future releases.

Render a PNG of the map. Two render engines:

• light (default) — a bundled minimal viewer (@deck.gl/carto fetchMap). ~2.5 MB asset, ~8 s cold start, ~10 MB network. Renders layers + basemap. No widgets, legends, popups, or chrome.

• full — the full CARTO Builder viewer at /viewer/:mapId rendered in a headless iframe. ~20 s, ~28 MB. Full feature parity.

carto maps screenshot abc123 -o map.png
carto maps screenshot abc123 --lat 40.42 --lng -3.70 --zoom 12 --hide-overlays
carto maps screenshot abc123 --render-engine full

Option	Description
--render-engine <e>	light (default) or full.
-o, --output <path>	Output file path (default: screenshot.png).
--width <px> / --height <px>	Viewport size (default: 1280 × 800).
--lat <deg> / --lng <deg>	Center coordinates.
--zoom <n> / --bearing <deg> / --pitch <deg>	Viewport.
--layers <indices>	Comma-separated visible layer indices (e.g. "0,2").
--search <query>	Address or "lat,lng" to center on.
--hide-overlays	Hide CARTO logo, attribution, zoom controls, legend.
--wait <seconds>	Optional pad after auto-detected render (default: 0).
--timeout <seconds>	Navigation/render timeout (default: 60).
--full-page	Capture full scrollable page instead of viewport.
--no-cache	Bypass persistent Chromium profile (full engine).

Optional Playwright install. maps screenshot launches a headless Chromium. The browser is an opt-in dependency to keep the CLI install small:

npm install playwright-core
npx playwright install chromium   # ~300 MB

The screenshot authenticates as the current CLI user, so it works on private, shared, and public maps you have access to.

carto maps delete

carto maps delete <map-id>
carto maps delete <map-id> --yes   # Skip confirmation

Examples

# Create from a bundle file
carto maps create < map.json

# Round-trip: get → edit → update
carto maps get abc123 --json > /tmp/map.json
jq '.title = "Q3 Dashboard"' /tmp/map.json | carto maps update abc123

# Validate locally (no network), then create
carto maps validate < map.json && carto maps create < map.json

# Update + publish in one go
carto maps update abc123 < shared.json --publish

# Agent introspection
carto maps agents status
carto maps schema layer.h3