# maps Manage CARTO Builder maps. Create, edit, validate, publish, copy across organizations, screenshot, and inspect the agent surface. ```bash carto maps list [options] # List maps carto maps get # Pretty details; --json emits round-trippable JSON carto maps create [json] # Create from JSON (positional, path, or stdin) carto maps update [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 # Freeze a snapshot so viewers see current state carto maps schema [section] # JSON Schema reference for agents carto maps agents # AI agent introspection (see below) carto maps datasets update # PATCH a single dataset on an existing map carto maps screenshot [options] # Save a PNG screenshot (opt-in Chromium) carto maps copy --dest-profile # Duplicate (cross-org or same org) carto maps delete # Delete map ``` ## The bundle model `maps get --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: ```bash 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: ```bash 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`](https://github.com/CartoDB/agent-skills/tree/master/skills/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 ` 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 ` | Free-text search across title/description. | | `--privacy ` | Filter by privacy: `private`, `shared`, `public`. | | `--tags ` | Filter by tags (JSON array, e.g. `'["demo","poc"]'`). | | `--order-by ` | Sort by `updatedAt`, `createdAt`, `title`. | | `--order-direction ` | `ASC` or `DESC`. | | `--page ` / `--page-size ` | 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 ` 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: ```bash 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`. ```bash carto maps schema layer.h3 carto maps schema uistate ``` ## `carto maps agents` Discover the AI surface available on the current tenant: ```bash 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. ```bash carto maps datasets update '{"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. ```bash # Auto-map connections by name (default) carto maps copy --dest-profile production # Manual mapping for renamed connections carto maps copy --dest-profile prod \ --connection-mapping "dev-bq=prod-bq,dev-sf=prod-sf" # Override source profile and title carto maps copy --source-profile staging --dest-profile prod \ --title "Production Map" ``` | Option | Description | | ---------------------------- | ----------------------------------------------------------------------------------- | | `--dest-profile ` | (Required) Destination profile name. | | `--source-profile ` | Source profile (default: current). | | `--connection-mapping ` | Per-source map (e.g. `"src1=dst1,src2=dst2"`). Preferred for multi-connection maps. | | `--connection ` | Legacy: single connection for all datasets. | | `--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-for-agents/cli/examples.md#copying-maps-and-workflows-between-organizations). ## `carto maps screenshot` {% hint style="info" %} `carto maps screenshot` is **experimental**. Its flags, render engines, and output may change in future releases. {% endhint %} 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. ```bash 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). | {% hint style="info" %} **Optional Playwright install.** `maps screenshot` launches a headless Chromium. The browser is an opt-in dependency to keep the CLI install small: ```bash 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. {% endhint %} ## `carto maps delete` ```bash carto maps delete <map-id> carto maps delete <map-id> --yes # Skip confirmation ``` ## Examples ```bash # 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 ``` --- # 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/command-reference/maps.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.