> 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](https://docs.carto.com/carto-for-agents/cli.md). For the full engineering changelog, see the source repository.

{% updates %}
{% update date="2026-11-10" %}

## v0.15.0

This release stops the CLI from changing a source's color in Builder, and catches more map and workflow mistakes before anything is saved.

{% hint style="warning" %}
**Breaking change.** `carto maps datasets update --color` was removed, and passing it is an error. Builder assigns each source's color, and users can't change it.
{% endhint %}

**Maps**

Changed

* **Breaking:** `carto maps datasets update --color` was removed. To change how a source is drawn, change its layer's colors.
* `carto maps update` keeps the color of every source the map already has. If the bundle sends a different color, the CLI keeps the stored one and says so in `notices` (`dataset.colorKept`).
* `carto maps validate`, `create` and `update` reject a `privacy` block that the map can't be saved with: unknown keys, `shared` without `sharingScope`, a password on a map that isn't public, `public` without `organization`, and repeated ids. Before, the sharing change could be skipped silently, or fail after the map was already saved.
* `carto maps validate`, `create` and `update` reject a range widget whose `min` isn't below its `max`. That map opened filtered to a single value, with no way to clear it.

**Workflows**

New

* `carto workflows mcp enable --input-description <input>=<description>` sets the description agents read for one of the tool's inputs, up to 500 characters. Repeat it for each input. The command warns about every input left without a description.

Changed

* `carto workflows create` and `update` warn when a node uses an older version of its component than the current one. The Workflows editor marks that node as outdated and won't run the workflow until you update it.

Fixed

* When an edge points at an input the node doesn't have, `carto workflows validate` now suggests the node's table inputs, instead of asking you to add the missing input.

**Apps**

Fixed

* `carto app deploy` accepts the provider a connection reports in `carto.json`. `postgres`, `databricksRest` and `databricksWarehouse` no longer fail validation.
  {% endupdate %}

{% update date="2026-11-03" %}

## v0.14.0

This release brings the workflow commands in line with Builder. You can share a workflow with groups and publish its current version, and enabling a workflow as an MCP tool or scheduling it now uses the same names and rules as the Workflows editor. The CLI also tells you when a newer version is available.

{% hint style="warning" %}
**Breaking changes.** `carto workflows mcp publish` / `unpublish` are now `mcp enable` / `disable`, and `carto workflows schedule add` / `remove` are now `schedule create` / `delete`. The old names exit with an error that names the new command.

These commands need a CARTO platform that serves the renamed tools. CARTO Cloud already does. On CARTO Self-Hosted, upgrade the platform before you upgrade the CLI: against an older platform the renamed commands fail with an unknown-tool error, and CLI 0.13.0 fails the same way against a newer one.
{% endhint %}

**General**

New

* The CLI tells you when a newer version is published. Once a day it checks npm in the background, and when a newer version exists, each command ends with a short notice that names it and the install command, whether the command succeeded or failed. Commands never wait for the check. The notice only appears in an interactive terminal, so `--json`, piped output and CI runs are unaffected. Set `CARTO_NO_UPDATE_NOTIFIER=1` to turn it off. See [Update notice](https://docs.carto.com/carto-for-agents/cli/configuration.md#update-notice).

**Workflows**

New

* [`carto workflows share --group`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md) and `carto workflows unshare --group` share a workflow with groups, or remove them, by group name or id. Names match exactly, ignoring case, and an unknown name fails the command, like an unknown email.
* [`carto workflows publish`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md#carto-workflows-publish) publishes a workflow's current version to everyone it's shared with, like **Publish updates** in the Workflows editor. It refuses a workflow that nobody else can access.
* `carto workflows schema node.input` documents a node's inputs, and `carto workflows schema edge` now declares `sourceHandle`, `targetHandle` and `type`.

Changed

* **Breaking:** `carto workflows mcp publish` and `unpublish` are now [`carto workflows mcp enable` and `disable`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md#carto-workflows-mcp). `mcp list` now reads "enabled as MCP tools", and the `--json` output of `mcp enable` no longer has a `mode` field.
* **Breaking:** `carto workflows mcp enable` always compiles the workflow and syncs its procedure to the warehouse, as Builder does. `--draft-only`, `--file` and `--from-file` were removed, and passing one is an error.
* `carto workflows mcp enable` refuses workflows on PostgreSQL and Databricks cluster connections, where Builder doesn't offer MCP tools either.
* **Breaking:** `carto workflows schedule add` and `remove` are now [`carto workflows schedule create` and `delete`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md#carto-workflows-schedule).
* `carto workflows schedule create` refuses what the Builder scheduler refuses: a workflow that has never run, Redshift connections, BigQuery OAuth connections without BigQuery Data Transfer, and connections whose warehouse permissions don't allow scheduled queries. Existing schedules can still be updated and deleted.
* `carto workflows schedule create` accepts standard cron on Oracle and Databricks Warehouse connections. Databricks clusters keep Quartz cron.
* `carto workflows run` records the run on the workflow, as Builder does, so a workflow you run from the CLI can be scheduled right after. If the run can't be recorded, the CLI prints a warning, and `--json` lists it under `warnings`.
* `carto workflows validate` checks a workflow against the same rules as the Workflows editor, so a workflow that passes validation opens in the editor. It now accepts raster and view sources on `ReadTable` nodes, Data Observatory and file nodes, and a bundle without `config` on create.
* `carto workflows validate` rejects what the editor can't open: a workflow privacy other than `private` or `shared` (`public` is no longer accepted), a group id that isn't a UUID, unknown keys in node data, a numeric `data.version`, and note nodes without `width`, `height`, `color` or `markdown`. On create, send `section` nodes as `note`.
* A node input whose value is an object is rejected, with a hint to send JSON values as a JSON-encoded string.
* `carto workflows validate` lists warnings in their own section, and warnings no longer make the command fail. `carto workflows update` now shows the warnings the server returns.
* `carto workflows schema components.input` shows the `validation` pattern an input value must match, in place of `providers`.

**Maps**

Changed

* `carto maps validate` rejects unknown fields at the root of a map bundle, which were previously dropped without a warning when the map was saved. The message lists the allowed fields, and when a field belongs somewhere else in the bundle, such as `widgets`, it says where to move it.
* `carto maps validate` checks `popupSettings` and accepts Builder's **Filter by feature** setting, `featureFilterScope` (`same-source`, `same-layer` or `all-layers`). It is rejected on raster, heatmap, cluster and static tileset layers.
* A table widget's `pageSize` must be `5`, `10` or `25`, the rows-per-page options Builder offers. Leave it out to get 5 rows.
* `carto maps validate` rejects two `sqlParameters` with the same `id`.
* An AI Agent without a `model` is accepted, as Builder saves it, which reverses the 0.13.0 rule. `semanticModel` is supported and must be valid YAML. Unknown fields in `agent.config` are rejected, with the list of allowed fields.
* `carto maps update` with a partial `agent` block keeps the stored value of every field you leave out, and lists the ones it kept. Send `""` or `[]` to clear a field.
* `carto maps schema` explains `aggregationExp`, popup templates, raster band expressions in popups, public sharing and how the widgets panel layout behaves on tablets and phones.
* [`carto maps agents core-tools`](https://docs.carto.com/carto-for-agents/cli/command-reference/maps.md#carto-maps-agents) lists the new `refresh_data_sources` tool, which lets an AI Agent reload the data on a map after a workflow changes it.

Fixed

* A bundle saved with `carto maps get` that has formula or table widgets passes `carto maps validate` again. It previously failed with `Unknown field 'disableFiltering'`.

**Hosted apps**

Changed

* `carto app schema carto-info` documents the viewer's `username` and `picture`.
* `carto app deploy` and `carto app package` reject a `carto.json` that declares the same source key in more than one connection.

**Platform**

These changes come from the CARTO platform rather than the CLI, so they apply to every CLI version once your platform has them. CARTO Cloud already does.

Maps

* Every successful `carto maps update`, `carto maps datasets update` and map change pushed by `carto projects push` records an automatic version in the map's history, so you can restore the previous state from Builder. With `--publish`, only the published version is recorded. If the version can't be recorded, the change is still saved and the command returns a `VERSION_FAILED` warning: don't repeat the update.
* `carto maps create` and `carto maps update` fail before writing anything when a new dataset can't render, for example because `geoColumn` is missing. The error points at the dataset's `geoColumn`. Before, the map was saved and only a warning was returned.
* `carto maps update` refuses a change that would reset the map's stored basemap, or its custom widgets panel layout. Send `basemapConfig` and `config.widgetsPanelLayout` again to keep them, or pass `--allow-kepler-replace`.
* `carto maps create` and `carto maps update` refuse to make a map public when its AI Agent can query sources for Viewers, and refuse to give a public map's Agent that capability. A public map's token can't run those queries, so the Agent would break for Viewers.
* `carto maps update` no longer warns that a map is unpublished when the same update shared it and the map was published automatically.
* `carto maps update --publish` with a privacy change publishes the map once. Before, a change that already published the map, such as a first share or a switch to public, published it a second time and left two published versions.
* Datasets with very long SQL queries, around 8 KB or more, no longer make `carto maps create` and `carto maps update` fail with `Tilejson rejected`.
* `carto maps verify-remote` warns when `featureFilterScope` is `all-layers` on a layer that draws points or lines, because that setting works only on polygon, H3 and quadbin layers.
* Claude Sonnet 5.5 is available as a CARTO Managed model and is the CARTO Managed default. It is listed by `carto maps agents models`.

Workflows

* `carto workflows run`, `to-sql`, `schedule create`, `schedule update`, `mcp enable` and `verify-remote` use the Analytics Toolbox of your region, as Builder does. On tenants outside the US they no longer fail with `Procedure is not found: carto-un.carto...`.
* `carto workflows mcp enable` works for workflows that use Analytics Toolbox components such as isolines. It refuses a workflow with invalid or unsupported nodes and names each one, instead of enabling a tool with those nodes missing.
* `carto workflows components get` lists only the inputs available on the connection's warehouse.
* Errors from `carto workflows run` and `carto sql job` no longer end with an internal `at gs://...js line N` location.

Imports, connections and AI

* `carto import` works with URLs that contain `*`, such as a CSV export link with `?$select=*`.
* `carto connections list --json` returns a shorter summary of each connection, without credential details. Use [`carto connections get`](https://docs.carto.com/carto-for-agents/cli/command-reference/connections.md) for the full record. In text output, the `Owner:` line no longer appears for a connection without an owner email.
* `carto connections search --json` no longer includes link fields, or ids that repeat a table's full name.
* AI features count as on only when an Admin has turned each one on. When you enable CARTO AI with `carto admin settings apply`, set `enabled: true` on every feature you want; `carto aifeature aiagent` returns a 403 error when Builder AI Agents is off. Organizations that already used AI features kept their settings.
* Stopping `carto aifeature aiagent` with Ctrl-C also stops the agent on the server.

Access

* Users with the **Viewer** role can use the CLI. Commands no longer fail with a 403 error after `carto auth login`. Authoring, admin and data-extraction commands stay unavailable to Viewers.
  {% endupdate %}

{% update date="2026-10-01" %}

## v0.13.0

This release brings the new [Builder map layout](https://docs.carto.com/carto-user-manual/maps/map-layout.md) to the CLI. You can now create and update maps with a floating or two-column widgets panel, full-width widgets and a set order for the parameters bar, and `carto maps validate` checks a map the same way Builder and the CARTO MCP server do.

**Requirements**

Changed

* The CLI now needs **Node.js 22 or later**. Check with `node --version` and upgrade Node before you run `npm i -g @carto/carto-cli`.

**Maps**

New

* [`carto maps schema widgetspanellayout`](https://docs.carto.com/carto-for-agents/cli/command-reference/maps.md) documents the widgets panel layout, set in `keplerMapConfig.config.widgetsPanelLayout`. Use `columns` (`1`, or `2` for widgets side by side) and `placement` (`docked` next to the map, or `floating` as a card over it). Without it, a map uses one docked column. With two columns, a widget with `fullWidth: true` takes a whole row.
* [`carto maps schema sqlparameters`](https://docs.carto.com/carto-for-agents/cli/command-reference/maps.md) explains that the order of `sqlParameters` is the order of the parameters bar, from left to right.

Changed

* `carto maps validate` and `carto maps schema` follow the same map rules as Builder and the CARTO MCP server, so a map that passes validation opens in Builder. When something is wrong, the message names the field and says how to fix it.
* `carto maps validate` rejects settings Builder would otherwise ignore or replace without telling you. For example, a widgets panel layout with `columns` other than `1` or `2`, a layer that points to a dataset missing from the map, or an AI Agent with more than four conversation starters. Maps saved from Builder pass as they are.
  {% endupdate %}

{% update date="2026-09-23" %}

## v0.12.0

The headline of this release is **connection sharing from the terminal**: share a connection with your organization, with specific people or with groups, and take that access back again, without opening the Workspace.

**Connections**

New

* New [`carto connections share`](https://docs.carto.com/carto-for-agents/cli/command-reference/connections.md) and [`carto connections unshare`](https://docs.carto.com/carto-for-agents/cli/command-reference/connections.md): share a connection with the whole organization (`--org`), with specific users by email (`--with`) or with groups by name or id (`--group`), list who has access (`--list`), and remove access again. New grants are added to what the connection already has. Sharing with users or groups needs a CARTO platform that supports connection access policies; on an older Self-hosted deployment the command stops with an upgrade message before changing anything. [Sharing a connection](https://docs.carto.com/carto-user-manual/connections/sharing-a-connection.md) in the user manual explains how a shared connection behaves for the people who receive it.
* [`carto connections get`](https://docs.carto.com/carto-for-agents/cli/command-reference/connections.md) shows who the connection is shared with.

**Imports**

New

* [`carto import`](https://docs.carto.com/carto-for-agents/cli/command-reference/imports.md) tells you when an import finished but lost rows. The job ends as `completed_with_warnings`, which the CLI treats as a success (the table exists), and it prints how many rows were dropped and why: rows without a readable location are in the table without geometry, rows with formatting errors were not imported. `--json` carries `metadata.droppedRows`, `droppedRowReasons` and `droppedRowsByReason`.

Fixed

* `carto import` streams the file to the upload URL instead of reading it into memory first, so files between 2 GiB and the 5 GB limit now import. They previously failed with `File size (...) is greater than 2 GiB`.

**Credentials**

Fixed

* `carto credentials update token --add-grant '<connection>,<SQL>'` keeps the whole SQL source: only the first comma separates the connection from the source. A malformed value now fails instead of silently storing a partial grant, and the source is required (pass `*` to grant every source).
* `carto credentials update token --connection <name> --source <source>` adds a grant, as `create token` does. Both flags were previously accepted and ignored.
* `carto credentials --help` documents the `update` flags (`--add-grant`, `--connection` with `--source`, `--add-api`, `--referers`, `--json-body`).

**Authentication**

Fixed

* `carto auth whoami` on an M2M profile reports the service identity (client id, account, acting user, API base URL, token expiry) instead of failing with `404 User not found`.
* After `carto auth login` with an account that belongs to no CARTO organization, commands now explain that an organization has to be created in the web app first, instead of asking to log in again.

**AI**

Fixed

* `carto aiproxy chat` and `carto ai` no longer answer "Authentication required" when your organization is not allowed to use the requested model. The proxy's own message is printed, including the models you can use; the login hint is kept for a session that is really invalid. Other proxy errors show their message plus `(HTTP n)`.

**Output**

Changed

* Backend failures are shown from the platform's error contract (title, error, detail), never from the raw response body, so a server stack trace can no longer appear in CLI output. `--json` error codes and per-field details are unchanged.

**Configuration**

Fixed

* The CLI honours `NO_PROXY` / `no_proxy` alongside `HTTPS_PROXY` / `HTTP_PROXY`, as curl and git do. Hosts it matches (exact host, `.domain` suffix, `*.domain`, `host:port`, `*`) are reached directly. Previously every request went through the proxy, so against a Self-Hosted instance on an internal-only hostname `carto auth login` worked but every tenant command failed with the proxy's own DNS error page. `carto activity` downloads now also use the configured proxy. See [Proxies](https://docs.carto.com/carto-for-agents/cli/configuration.md#proxies).

**Users**

Breaking changes

* [`carto users list`](https://docs.carto.com/carto-for-agents/cli/command-reference/users.md) drops `--all`, `--page`, `--page-size`, `--role` and `--search`. The API never implemented them: every call returned the organization's full roster, and `--all` never finished for organizations of 100 or more users. A plain `carto users list` returns everyone; filter the output instead, for example `carto users list --json | jq '[.[] | select(.email | contains("ana"))]'`.

**Hosted apps**

New

* The [`carto app`](https://docs.carto.com/carto-for-agents/cli/command-reference/app.md) command group now appears in `carto --help` and in the command catalogue. It requires the Hosted Apps feature on your account; when the feature is not available, or the CARTO deployment predates it, the commands say so and explain how to request access instead of failing with a 404 (`--json` adds `"code": "hosted-apps-feature-disabled"`).
* [`carto app schema [section]`](https://docs.carto.com/carto-for-agents/cli/command-reference/app.md) prints the JSON Schema for `carto.json` (the deploy manifest) and `carto-info.json` (the runtime bootstrap), with every field described. Runs offline.
* [`carto app check <dir>`](https://docs.carto.com/carto-for-agents/cli/command-reference/app.md) is an offline safety report before a bundle goes public: the grants a public token would need, blocked SQL (DDL, multi-statement, line comments, writes unless `--allow-writes`), and a secret scan of the bundle. Exit 1 when blocked.
* [`carto app package <dir>`](https://docs.carto.com/carto-for-agents/cli/command-reference/app.md) builds a public version of a bundle you host yourself: registers the manifest's named sources, mints one least-privilege API Access Token locked to `--url` (one year for read-only grants, 30 days with writes, `--expires` to change), verifies it, revokes the earlier tokens for the slug, and writes `carto-info.json` next to a copy of the bundle. `--dry-run`, `--skip-verify`, `--show-token`, `--update-referer`.
* `carto.json` connections accept `tables` and `statements`, used only to scope the public token when packaging; `carto app deploy` ignores them.

**Agents**

New

* Entries in `carto --commands --json` can carry a `docs` deep link to their reference page, so an agent can point a user at the documentation for the command it just ran.
* [`carto maps schema`](https://docs.carto.com/carto-for-agents/cli/command-reference/maps.md) and [`carto workflows schema`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md) serve the same section catalogue the MCP server now exposes to agents. Output is unchanged except that ten sections gain a root description, and strings that told the reader to run a CLI command now name the capability instead.
  {% endupdate %}

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

## 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`](https://docs.carto.com/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](https://docs.carto.com/carto-user-manual/maps/layers.md#stroke-styles) and [Fill patterns](https://docs.carto.com/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`](https://docs.carto.com/carto-for-agents/cli/command-reference/maps.md) and [`update`](https://docs.carto.com/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" %}

## 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`](https://docs.carto.com/carto-for-agents/cli/command-reference/lds.md) command group.

**Location Services**

New

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

**SQL**

Breaking changes

* [`carto sql query`](https://docs.carto.com/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`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md) and [`unshare`](https://docs.carto.com/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`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md), [`create`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md), and [`update`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/carto-for-agents/cli/command-reference/maps.md) and [`update`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md) and [`carto maps list`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/carto-for-agents/cli/command-reference/credentials.md) documents the `exports` scope, which [`carto export`](https://docs.carto.com/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" %}

## v0.9.2

**Users**

New

* [`carto users get`](https://docs.carto.com/carto-for-agents/cli/command-reference/users.md) and [`carto users delete`](https://docs.carto.com/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](https://docs.carto.com/carto-for-agents/cli/command-reference/users.md#identifying-a-user).

**Workflows**

New

* [`carto workflows share`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md) and [`unshare`](https://docs.carto.com/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" %}

## v0.9.0

**Workflows**

Breaking changes

* [`carto workflows validate`](https://docs.carto.com/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`](https://docs.carto.com/carto-for-agents/cli/command-reference/workflows.md) and [`update`](https://docs.carto.com/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`](https://docs.carto.com/carto-for-agents/cli/command-reference/sql.md) and [`carto sql job`](https://docs.carto.com/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`](https://docs.carto.com/carto-for-agents/cli/command-reference/sql.md) also accepts a [named source](https://docs.carto.com/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`](https://docs.carto.com/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" %}

## v0.8.0

**Workflows**

Breaking changes

* [`carto workflows verify-remote`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/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`](https://docs.carto.com/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" %}

## v0.7.1

**Maps**

Improvement

* The `add_layer` core tool surfaced by [`carto maps agents core-tools`](https://docs.carto.com/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" %}

## v0.7.0

This release introduces **map and workflow authoring from the command line** and lands alongside the new [CARTO for Agents](https://docs.carto.com/carto-for-agents/carto-for-agents.md) section, which brings the CLI together with the [CARTO MCP Server](https://docs.carto.com/carto-for-agents/mcp-server.md) and the [Agent Skills](https://docs.carto.com/carto-for-agents/agent-skills.md) catalog.

**Maps**

New

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

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

## v0.6.0

Breaking changes

* [`carto export`](https://docs.carto.com/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" %}

## 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" %}

## 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
