# CARTO CLI

The **CARTO CLI** (`@carto/carto-cli`) is the official command-line interface for CARTO. It exposes nearly every platform operation as a scriptable command. Find and manage maps, workflows, connections and credentials, import and export geospatial data, run SQL on connected warehouses, manage users, audit activity, transfer assets between organizations, and chat with the AI agents configured on your maps.

The CLI is designed to be driven by:

* **Humans** at the terminal, for one-off admin tasks, scripting, and CI/CD.
* **AI agents** like Claude Code, Cursor, Codex, or Gemini CLI through tool use. The `--json` global flag gives agents machine-readable output for every command.

<figure><img src="/files/2A3IEtNlrR8IIklt6On3" alt="" width="563"><figcaption></figcaption></figure>

## Capabilities

* **Builder maps**. Create, update, validate, publish, and copy CARTO Builder maps from a round-trippable JSON bundle. Inspect the AI agent surface available on each map. (Map `screenshot` is also available as an experimental command.)
* **Workflows**. Create, update, validate, verify, run, schedule, share, and publish CARTO Workflows. Publish a workflow as an MCP tool so any connected agent can call it. Install workflow extensions and browse the component catalog.
* **Projects (folders)**. Group maps and workflows into projects, with a local-sync workflow that lets you clone, edit, and push changes back from your machine.
* **Credentials**. Create and manage API Access Tokens, SPA OAuth clients, M2M OAuth clients, and Named Sources.
* **Connections**. List, create, update, and delete data warehouse connections. Browse the resource tree, search tables, and describe schemas.
* **Data Observatory**. Browse, search, and subscribe to spatial datasets from CARTO's public and premium catalog.
* **Data movement**. Import geospatial files (CSV, GeoJSON, GeoPackage, GeoParquet, KML, KMZ, Shapefile) from local files or URLs. Export warehouse tables back out, or transfer data between warehouses.
* **SQL**. Run SQL queries and DDL/DML jobs against your data warehouse from the terminal.
* **Organization and users**. View quotas, resources, and AI limits. List, invite, and manage users and pending invitations.
* **Activity data**. Query and export usage logs via DuckDB SQL (Enterprise Large+).
* **Superadmin operations**. Batch operations and cross-org resource transfers.
* **Multi-profile support**. Manage multiple CARTO accounts or environments with named profiles. Tokens are stored locally in `~/.carto_credentials.json`.
* **Single executable**. Bundled into one file with minimal dependencies.
* **JSON output**. Machine-readable output (`--json`) on every command for scripting and agent tool use.

## Get started

1. [Install the CLI](/carto-for-agents/cli/installation.md).
2. [Authenticate](/carto-for-agents/cli/authentication.md) to your CARTO organization with `carto auth login`. Configure additional [named profiles](/carto-for-agents/cli/authentication.md#multiple-profiles) if you work with several organizations.
3. [Browse the command reference](/carto-for-agents/cli/command-reference.md) to see every available command, flag, and example.
4. Walk through end-to-end [examples](/carto-for-agents/cli/examples.md): creating Builder maps and workflows from JSON, copying assets between organizations, scheduling workflows, importing data, and querying activity logs.

If you're driving the CLI from an AI coding agent, also see [CARTO Agent Skills](/carto-for-agents/agent-skills.md), the catalog of skills that teach Claude Code, Cursor, Codex, and Gemini CLI how to use the CLI idiomatically.


---

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