> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/cli/release-notes.md).

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

{% updates %}
{% update date="2026-09-01" %}

## September 1st, 2026 (v0.11.0)

The headline of this release is **stroke styles and polygon fill patterns**, now available when you author maps from the terminal. A map written with the CLI can carry the same styling a Builder user sets by hand.

**Maps**

New

* Layer `visConfig` accepts **stroke styles** on line geometries and polygon borders: `lineStyle` (`solid`, `dashed`, `dotted`), `dashArray` as a `[dash, gap]` pair relative to the stroke width, and `lineStyleRange` to drive the style from a column when `lineStyleField` is set.
* Layer `visConfig` accepts **polygon fill patterns**: `fillPatternEnabled` switches a polygon from solid fill to pattern, `fillPattern` selects one of `hlines`, `vlines`, `diag-left`, `diag-right`, `cross-hatch`, `dots`, `checker`, `fillPatternDensity` takes `small`, `medium` or `large`, `fillPatternSize` scales the pattern from `0.1` to `5` (`1` = 100%), and `fillPatternRange` drives the pattern from a column when `fillPatternField` is set. Per-category entries additionally accept `solid` (flat fill color) and `none` (unpainted).
* [`carto maps schema`](/carto-for-agents/cli/command-reference/maps.md) reports the new fields, so agents can discover them without reading these notes.

Builder renders stroke styles and fill patterns on **tileset (`mvt`)** layers. `h3` and `quadbin` layers accept the same fields — so a stored map survives a future re-enable — but do not render them yet.

For what these look like in Builder, see [Stroke styles](/carto-user-manual/maps/layers.md#stroke-styles) and [Fill patterns](/carto-user-manual/maps/layers.md#fill-patterns) in the user manual.

**Agents**

Breaking changes

* Map writes now reject agent configs that exceed the caps Builder's agent dialog enforces, instead of accepting them and producing a map that Builder cannot subsequently edit. [`carto maps create`](/carto-for-agents/cli/command-reference/maps.md) and [`update`](/carto-for-agents/cli/command-reference/maps.md) fail when `config.useCase` is over 500 characters, `config.introduction.starters` has more than 4 entries, `config.introduction.welcome` is over 300 characters, or any single starter is over 100 characters. A bundle with more than 4 starters previously saved and then failed the viewer with a 500. Trim these fields to bring an existing bundle back within the caps.
  {% endupdate %}

{% update date="2026-08-31" %}

## August 31st, 2026 (v0.10.2)

The headline of this release is **Location Data Services from the terminal**: geocoding, reverse geocoding, isolines, routing, and origin-destination matrices, all under the new [`carto lds`](/carto-for-agents/cli/command-reference/lds.md) command group.

**Location Services**

New

* New [`carto lds`](/carto-for-agents/cli/command-reference/lds.md) command group brings CARTO Location Data Services to the terminal: [`geocode`](/carto-for-agents/cli/command-reference/lds.md), [`reverse-geocode`](/carto-for-agents/cli/command-reference/lds.md), [`isolines`](/carto-for-agents/cli/command-reference/lds.md), [`routing`](/carto-for-agents/cli/command-reference/lds.md), [`od-matrix`](/carto-for-agents/cli/command-reference/lds.md), and [`capabilities`](/carto-for-agents/cli/command-reference/lds.md) (which reports your provider and remaining quota per operation). Every subcommand supports `--json`.

**Transfer**

New

* [`carto transfer`](/carto-for-agents/cli/command-reference/transfer.md) gains `--overwrite` to replace an existing destination table (staged, so the current table survives a failed transfer), `--target-srid <epsg>` to reproject geometry at the destination, and `--preserve-source-crs` to keep the source CRS instead of applying the destination's convention.

**SQL**

Breaking changes

* [`carto sql query`](/carto-for-agents/cli/command-reference/sql.md) no longer accepts `--cache`. The flag issued a cached `GET` that no longer cached anything and capped query length at roughly 8 KB. `sql query` now always `POST`s, with no length limit. Remove `--cache` from any script that passes it.

**Workflows**

Breaking changes

* [`carto workflows share`](/carto-for-agents/cli/command-reference/workflows.md) and [`unshare`](/carto-for-agents/cli/command-reference/workflows.md) no longer accept `--user-id` or `--user-email`. Identify users with `--with <email>`, which is repeatable and comma-separated. This withdraws the `--user-id` / `--user-email` flags that `0.9.1` and `0.9.2` introduced. Any user with an email is still reachable; sharing by user ID alone is tracked as a separate request.

Fix

* [`carto workflows get`](/carto-for-agents/cli/command-reference/workflows.md), [`create`](/carto-for-agents/cli/command-reference/workflows.md), and [`update`](/carto-for-agents/cli/command-reference/workflows.md) now honor `--profile`. The flag was silently ignored on these three subcommands, so cross-org flows went out with the default profile's token and failed with a misleading "Permission denied".
* [`carto workflows validate`](/carto-for-agents/cli/command-reference/workflows.md) now reports an edge whose `targetHandle` names an input the target node does not declare. Such an edge draws no connection line on the canvas even though the engine still runs it, so it previously surfaced only as a broken-looking DAG.

**Maps**

Fix

* [`carto maps create`](/carto-for-agents/cli/command-reference/maps.md) and [`update`](/carto-for-agents/cli/command-reference/maps.md) no longer reject accessible Oracle (and other non-BigQuery) sources. The pre-create source probe used BigQuery-only SQL against every warehouse, so valid sources failed as false negatives. The probe now speaks each provider's dialect and surfaces the real warehouse error.

New

* [`carto maps validate`](/carto-for-agents/cli/command-reference/maps.md) rejects single-select Category SQL parameters that would load inconsistently in Builder.

**Listing**

Fix

* [`carto workflows list`](/carto-for-agents/cli/command-reference/workflows.md) and [`carto maps list`](/carto-for-agents/cli/command-reference/maps.md) with `--order-by updatedAt` (or `createdAt`) no longer return HTTP 500. The camelCase forms the help advertises are now normalized before the request.

**Imports**

Fix

* [`carto imports`](/carto-for-agents/cli/command-reference/imports.md) accepts files up to 5 GB, matching the server. A stale client-side guard had rejected anything over 1 GB.

**Authentication**

Fix

* `--base-url` no longer requires the default profile's tenant to be reachable, so an override works even when that tenant is not. An empty `--token` now errors clearly instead of silently falling back to the stored profile.

**Credentials**

Improvement

* [`carto credentials create token --apis`](/carto-for-agents/cli/command-reference/credentials.md) documents the `exports` scope, which [`carto export`](/carto-for-agents/cli/command-reference/export.md) requires.

**Security**

Improvement

* The CLI writes `~/.carto/config.json` with owner-only (`0600`) permissions, and masks the `aiproxy` API key in command output.
  {% endupdate %}

{% update date="2026-07-30" %}

## July 30th, 2026 (v0.9.2)

**Users**

New

* [`carto users get`](/carto-for-agents/cli/command-reference/users.md) and [`carto users delete`](/carto-for-agents/cli/command-reference/users.md) now take an explicit `--user-id` or `--user-email` flag to say which user you mean, and `users delete` takes `--receiver-id` or `--receiver-email` for the user who inherits the content. Both commands used to infer the kind from the value and read anything containing an `@` as an email, so a user whose SSO ID contains one (`samlp|my-sso|jane@carto.com`) could not be targeted at all. See [Identifying a user](/carto-for-agents/cli/command-reference/users.md#identifying-a-user).

**Workflows**

New

* [`carto workflows share`](/carto-for-agents/cli/command-reference/workflows.md) and [`unshare`](/carto-for-agents/cli/command-reference/workflows.md) accept `--user-id` alongside `--user-email`, both repeatable and comma-separated. Sharing with a user by ID was not possible before, so SSO users whose ID contains an `@` were out of reach here too.

**All commands**

Improvement

* Flags accept the `--flag=value` form in addition to `--flag value`. This is the only way to pass a value that itself starts with `--`.
  {% endupdate %}

{% update date="2026-06-29" %}

## June 29th, 2026 (v0.9.0)

**Workflows**

Breaking changes

* [`carto workflows validate`](/carto-for-agents/cli/command-reference/workflows.md) now validates against the connection's **live component catalog** instead of running fully offline. On top of the structural checks, it confirms that every component name and parameter exists in the connection's catalog — native functions, extensions, and stored procedures. As a result it needs a connection (read from the bundle's `connectionId`, or supplied with the new `--connection <name|uuid>` flag) and an authenticated session. [`carto workflows create`](/carto-for-agents/cli/command-reference/workflows.md) and [`update`](/carto-for-agents/cli/command-reference/workflows.md) run the same catalog-aware pre-flight before submitting.

{% hint style="warning" %}
**Migration**: `workflows validate` previously made no API calls. If you run it in CI, make sure the bundle carries a `connectionId` (or pass `--connection`) and that the environment is authenticated.
{% endhint %}

**SQL**

New

* [`carto sql query`](/carto-for-agents/cli/command-reference/sql.md) and [`carto sql job`](/carto-for-agents/cli/command-reference/sql.md) accept `--param key=value` (repeatable) and `--params-json '<json>'` to bind query parameters. `--param` values are JSON-parsed — numbers, booleans, and arrays keep their type, everything else is treated as a string — while `--params-json` takes a full JSON object or array for complete control. The two flags can't be combined.
* [`carto sql query`](/carto-for-agents/cli/command-reference/sql.md) also accepts a [named source](/carto-for-agents/cli/command-reference/named-sources.md) name in the SQL position, so you can run a saved query by name (and bind its parameters with `--param`) without writing the SQL by hand.

**Admin**

Fix

* [`carto admin settings apply`](/carto-for-agents/cli/command-reference/admin.md) now reports any models the API failed to apply, so partial failures surface instead of appearing to succeed.
  {% endupdate %}

{% update date="2026-05-29" %}

## 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.
  {% endupdate %}

{% update date="2026-05-14" %}

## 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).
  {% endupdate %}

{% update date="2026-05-13" %}

## 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 %}
{% endupdate %}

{% update date="2026-04-27" %}

## 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 %}
{% endupdate %}

{% update date="2026-04-25" %}

## 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.
  {% endupdate %}

{% update date="2025-12-31" %}

## 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.
  {% endupdate %}
  {% endupdates %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-for-agents/cli/release-notes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.