Release notes

This page tracks user-visible changes to the CARTO CLI. For the full engineering changelog, see the source repository.

May 29th, 2026 (v0.8.0)

Workflows

Breaking changes

• carto workflows verify-remote no longer fails on advisory warnings. The exit code (and the valid field on --json output) now reflects whether the workflow would be accepted by workflows create. Warnings are still listed in the output, but on their own they no longer break the run.

Migration: if you have a CI gate that relied on any warning failing the build, pass the new --strict flag to restore the previous behaviour.

New

• carto workflows verify-remote --strict restores the previous behaviour, where any warning fails the exit code. Useful for CI gates that want to enforce a clean run.

Improvement

• carto workflows components get --json now returns the human-readable option labels alongside the values that components accept. For inputs like native.isolines.mode, bundle authors can pick the value the engine expects ("walk") without mistaking it for the display label ("Walk").

• carto workflows create accepts both a stringified FeatureCollection and a FeatureCollection object on the native.tablefromgeojson and native.drawcustomgeographies components, so workflows that ingest GeoJSON can now be authored from the CLI.

Fix

• carto workflows create now prints the canonical workflow URL on success, so callers no longer have to assemble it themselves.

Maps

Improvement

• carto maps schema layers now lists the four Scale with zoom level radius fields for tileset point layers — radiusScaleWithZoom, radiusReferenceZoom, sizeMinPixels, sizeMaxPixels — so bundle authors can discover the mode. carto maps validate also rejects two shapes that would silently break in Builder: radiusScaleWithZoom: true without a radius value, and radiusScaleWithZoom: true alongside a radiusField.

Fix

• carto maps create now emits the correct Builder URL. The URL could previously fall back to a different host that returned 404.

Connections

Fix

• carto connections browse --max-items and --max-children are now honoured. Both flags were silently dropped, so browse output capped at 30 items regardless of value.

Credentials

New

• carto credentials create token accepts wildcard --source patterns (e.g. "carto.shared.CARTO_*", or "*" for all sources on the connection), an --expiration-date flag (ISO date or shorthand like 30d / 6m / 1y), and an optional --name label, so a single token can be scoped to a fleet of warehouses and aged out automatically.

Admin

New

• carto admin settings get|apply|diff round-trips org-wide administrative settings (basemaps toggles, palettes, maps, connections, workflows, builder-gen-ai, carto-ai) as a single JSON bundle. Useful for moving settings between environments or capturing a snapshot for audit.

May 14th, 2026 (v0.7.1)

Maps

Improvement

• The add_layer core tool surfaced by carto maps agents core-tools now accepts clickColumns and clickColumnsAggregation, so the Builder AI agent can author click popups end-to-end (previously only hover popups were configurable). Aggregation rules mirror hoverColumns / hoverColumnsAggregation, and clickColumns has no field-count cap (the hover cap of 5 still applies).

May 13th, 2026 (v0.7.0)

This release introduces map and workflow authoring from the command line and lands alongside the new CARTO for Agents section, which brings the CLI together with the CARTO MCP Server and the Agent Skills catalog.

Maps

New

• Author Builder maps end-to-end from the CLI. carto maps create and carto maps update accept a round-trippable JSON bundle as a positional argument, a filesystem path, or via stdin. The bundle returned by maps get --json can be piped straight back into create or update.

• New commands round out the authoring loop: maps validate (offline pre-flight, no API calls), maps verify-remote (pre-flight plus warehouse-side dry-runs), maps publish (freeze a snapshot so shared and public viewers see the current state), maps schema (JSON Schema reference for bundle authors), maps agents (inspect the AI surface available on a tenant), and maps copy --dest-profile (duplicate a map across organizations).

• maps create and maps update responses now expose builderUrl, viewerUrl, and publicUrl as first-class fields.

Improvement

• Bundles are pre-flight validated before any API call, with clear pointers to the offending field on failure. Broken sources, missing required fields, and shapes that would render incorrectly in Builder are rejected locally.

• Sensible defaults are auto-filled when bundle fields are omitted (popup enabled, widget operationColumn, collapsible, basemap and viewport hydration from /stats), so smaller bundles "just work".

Workflows

New

• Author and validate workflows from the CLI. carto workflows create, update, and validate (offline schema check), plus the new workflows verify command — warehouse-aware validation that requires --connection <name|uuid> and runs the full structural, engine-compile, schema-trace, and sources stack without writing the workflow.

• carto workflows components list and get surface the agent-facing component catalog. Both require --connection <name|uuid> so extension and stored-procedure components appear alongside native ones.

Fix

• carto workflows list --order-by updated|created no longer fails with a 500. The CLI now aliases updated → updated_at and created → created_at before calling the API. Canonical values still work unchanged.

For end-to-end recipes — including the agent skills that drive these flows — see the carto-create-builder-maps and carto-create-workflow skills in the agent-skills repository, and the CARTO for Agents section.

April 27th, 2026 (v0.6.0)

Breaking changes

• carto export no longer accepts --query. Use --select <cols> (comma-separated column list) and --where <predicate> (warehouse-native SQL, no leading WHERE) instead. --limit is unchanged.

Migration: rewrite carto export --query "SELECT a, b FROM t WHERE c > 0" as carto export <t> --select a,b --where "c > 0".

April 25th, 2026 (v0.5.0)

Fix

• Kebab-case flag forms (--page-size, --order-by, --order-direction, --max-children) on list commands now work as documented across maps, workflows, connections, users, credentials, and admin. The camelCase forms (--pageSize, --orderBy, …) continue to work as aliases.

December 31st, 2025 (v0.1.0)

New

• Initial release of the CARTO CLI.

• Multi-profile authentication, including M2M OAuth for CI/CD pipelines.

• Commands for maps, workflows, connections, credentials, users, imports, and admin, with JSON output mode for scripting.