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.

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.

2. Authenticate to your CARTO organization with carto auth login. Configure additional named profiles if you work with several organizations.

3. Browse the command reference to see every available command, flag, and example.

4. Walk through end-to-end examples: 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, the catalog of skills that teach Claude Code, Cursor, Codex, and Gemini CLI how to use the CLI idiomatically.