# Release notes

This page tracks user-visible changes to the [CARTO CLI](/carto-for-agents/cli.md). For the full engineering changelog, see the source repository.

## May 29th, 2026 (v0.8.0)

**Workflows**

Breaking changes

* [`carto workflows verify-remote`](/carto-for-agents/cli/command-reference/workflows.md) 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.

{% hint style="warning" %}
**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.
{% endhint %}

New

* [`carto workflows verify-remote --strict`](/carto-for-agents/cli/command-reference/workflows.md) 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`](/carto-for-agents/cli/command-reference/workflows.md) 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`](/carto-for-agents/cli/command-reference/workflows.md) 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`](/carto-for-agents/cli/command-reference/workflows.md) now prints the canonical workflow URL on success, so callers no longer have to assemble it themselves.

**Maps**

Improvement

* [`carto maps schema layers`](/carto-for-agents/cli/command-reference/maps.md) 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`](/carto-for-agents/cli/command-reference/maps.md) 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`](/carto-for-agents/cli/command-reference/maps.md) 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`](/carto-for-agents/cli/command-reference/connections.md) 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`](/carto-for-agents/cli/command-reference/credentials.md) 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`](/carto-for-agents/cli/command-reference/admin.md) 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`](/carto-for-agents/cli/command-reference/maps.md) 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](/carto-for-agents/carto-for-agents.md) section, which brings the CLI together with the [CARTO MCP Server](/carto-for-agents/mcp-server.md) and the [Agent Skills](/carto-for-agents/agent-skills.md) catalog.

**Maps**

New

* Author Builder maps end-to-end from the CLI. [`carto maps create`](/carto-for-agents/cli/command-reference/maps.md) and [`carto maps update`](/carto-for-agents/cli/command-reference/maps.md) 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`](/carto-for-agents/cli/command-reference/maps.md) (offline pre-flight, no API calls), [`maps verify-remote`](/carto-for-agents/cli/command-reference/maps.md) (pre-flight plus warehouse-side dry-runs), [`maps publish`](/carto-for-agents/cli/command-reference/maps.md) (freeze a snapshot so shared and public viewers see the current state), [`maps schema`](/carto-for-agents/cli/command-reference/maps.md) (JSON Schema reference for bundle authors), [`maps agents`](/carto-for-agents/cli/command-reference/maps.md) (inspect the AI surface available on a tenant), and [`maps copy --dest-profile`](/carto-for-agents/cli/command-reference/maps.md) (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`](/carto-for-agents/cli/command-reference/workflows.md), [`update`](/carto-for-agents/cli/command-reference/workflows.md), and [`validate`](/carto-for-agents/cli/command-reference/workflows.md) (offline schema check), plus the new [`workflows verify`](/carto-for-agents/cli/command-reference/workflows.md) 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`](/carto-for-agents/cli/command-reference/workflows.md) and [`get`](/carto-for-agents/cli/command-reference/workflows.md) 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.

{% hint style="info" %}
For end-to-end recipes — including the agent skills that drive these flows — see the [`carto-create-builder-maps`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-builder-maps) and [`carto-create-workflow`](https://github.com/CartoDB/agent-skills/tree/master/skills/carto-create-workflow) skills in the [agent-skills repository](https://github.com/CartoDB/agent-skills), and the [CARTO for Agents](/carto-for-agents/carto-for-agents.md) section.
{% endhint %}

## April 27th, 2026 (v0.6.0)

Breaking changes

* [`carto export`](/carto-for-agents/cli/command-reference/export.md) no longer accepts `--query`. Use `--select <cols>` (comma-separated column list) and `--where <predicate>` (warehouse-native SQL, no leading `WHERE`) instead. `--limit` is unchanged.

{% hint style="warning" %}
**Migration**: rewrite `carto export --query "SELECT a, b FROM t WHERE c > 0"` as `carto export <t> --select a,b --where "c > 0"`.
{% endhint %}

## 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.


---

# 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/release-notes.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.