carto-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

carto-basics

CARTO基础入门

CARTO is reachable through two parallel access paths, and most agent setups use one or both:

CARTO CLI (
```
@carto/carto-cli
```
) — the primary path for authoring, scripting, and headless contexts. Used by most other skills in this catalog.
CARTO MCP Server — a parallel path for inline interactions in chat-based agent hosts (Claude.ai, Claude Desktop, ChatGPT). Renders maps inline, exposes data discovery and saved-Builder-map preview tools, and dynamically registers the user's saved CARTO Workflows as MCP tools when available.

Use this skill before any other CARTO skill — it covers installation, authentication, profiles, the global CLI flags every other CARTO skill assumes, and how to detect / route between the two access paths.

CARTO可通过两条并行路径访问，大多数Agent配置会使用其中一条或两条：

CARTO CLI (
```
@carto/carto-cli
```
) — 是创作、脚本编写和无头环境下的主要访问路径，本技能目录中的大多数其他技能都会用到它。
CARTO MCP Server — 是用于基于聊天的Agent宿主（Claude.ai、Claude Desktop、ChatGPT）中内联交互的并行路径。支持在聊天中内联渲染地图，提供数据发现和已保存Builder地图预览工具，并在可用时将用户保存的CARTO Workflows动态注册为MCP工具。

在使用任何其他CARTO技能前，请先掌握本技能——它涵盖了安装、身份验证、配置文件、其他所有CARTO技能默认依赖的全局CLI标志，以及如何检测和在两条访问路径间进行路由。

When to use this skill

何时使用本技能

Setting up the CLI for the first time on a new machine.
The user reports authentication errors (
```
auth status
```
failures, expired tokens).
The user wants to switch between organizations or environments.
A downstream skill needs
```
--profile
```
,
```
--json
```
,
```
--token
```
, or
```
--base-url
```
and you don't yet know how those work.

在新机器上首次设置CLI时。
用户报告身份验证错误（
```
auth status
```
失败、令牌过期）时。
用户想要在组织或环境间切换时。
下游技能需要使用
```
--profile
```
、
```
--json
```
、
```
--token
```
或
```
--base-url
```
参数，而你尚不了解这些参数的用法时。

Quick start

快速开始

bash

npm install -g @carto/carto-cli
carto auth login                # opens browser, stores credentials
carto auth status               # confirms tenant, org, user
carto maps list --json          # any command can return JSON

Authentication state persists across sessions.

auth status

is the fastest way to confirm the agent has working credentials before doing anything else.

bash

npm install -g @carto/carto-cli
carto auth login                # 打开浏览器，存储凭证
carto auth status               # 确认租户、组织、用户信息
carto maps list --json          # 任何命令都可返回JSON格式输出

身份验证状态会在会话间持久化。在执行其他操作前，

auth status

是确认Agent具备有效凭证的最快方式。

What's in this skill

本技能涵盖内容

Topic	Reference
Installing the CLI (npm, version verification)	references/installation.md
Authentication: browser, headless `--no-launch-browser` , API tokens, SSO	references/authentication.md
Profiles: managing multiple orgs / environments	references/profiles.md
Global flags: `--json` , `--debug` , `--yes` , `--token` , `--base-url` , `--profile` , env vars	references/global-options.md

主题	参考链接
安装CLI（npm、版本验证）	references/installation.md
身份验证：浏览器登录、无头模式 `--no-launch-browser` 、API令牌、SSO	references/authentication.md
配置文件：管理多个组织/环境	references/profiles.md
全局标志： `--json` 、 `--debug` 、 `--yes` 、 `--token` 、 `--base-url` 、 `--profile` 、环境变量	references/global-options.md

Access paths: CLI vs MCP server

访问路径：CLI vs MCP服务器

The two paths serve different intents. Most agent flows pick one based on what the user is asking for; some flows chain across both.

User intent	Preferred path	Skill
Author or edit a permanent CARTO Builder map (CRUD on saved maps, validation, publish)	CLI	`carto-create-builder-maps`
Render an ad-hoc, exploratory map inline in chat from a deck.gl declarative spec	MCP ( `view_map` )	`carto-render-inline-map`
Open / preview an existing saved Builder map by URL, ID, or name	MCP ( `load_builder_map` + `list_maps` )	`carto-preview-builder-map`
Build a from-scratch CARTO + deck.gl app in TypeScript / JavaScript	(developer code)	`carto-develop-app`
Discover what's in a connection — schemas, tables, named sources	CLI today; MCP equivalents ( `list_connections` , `list_resources` , `search_resources` , `get_column_stats` ) when attached	`carto-explore-datawarehouse` (CLI) — MCP-aware refactor pending
Run spatial SQL	CLI today	`carto-query-datawarehouse` (CLI) — MCP-aware refactor pending
Author a Workflow (DAG of analytical components)	CLI today	`carto-create-workflow` (CLI) — MCP-aware refactor pending
Run a saved Workflow as an analytical tool	MCP, when the Workflow is registered as an MCP tool (dynamic per account)	covered ad-hoc by host's tool-list — no dedicated skill yet
Geospatial pattern analyses (hotspots, GWR, spatial autocorrelation, etc.)	CLI (Workflows)	`carto-pattern-*` skills

两条路径适用于不同场景。大多数Agent流程会根据用户需求选择其中一条；部分流程会在两条路径间切换。

用户需求	首选路径	对应技能
创建或编辑永久的CARTO Builder地图（对已保存地图进行增删改查、验证、发布）	CLI	`carto-create-builder-maps`
在聊天中根据deck.gl声明式规范内联渲染临时探索性地图	MCP ( `view_map` )	`carto-render-inline-map`
通过URL、ID或名称打开/预览已保存的CARTO Builder地图	MCP ( `load_builder_map` + `list_maps` )	`carto-preview-builder-map`
使用TypeScript/JavaScript从零构建CARTO + deck.gl应用	（开发者代码）	`carto-develop-app`
探索连接中的内容——模式、表格、命名数据源	当前为CLI；当连接后可使用MCP等效工具（ `list_connections` 、 `list_resources` 、 `search_resources` 、 `get_column_stats` ）	`carto-explore-datawarehouse` （CLI）——支持MCP的重构版本待发布
运行空间SQL	当前为CLI	`carto-query-datawarehouse` （CLI）——支持MCP的重构版本待发布
创建Workflow（分析组件的DAG）	当前为CLI	`carto-create-workflow` （CLI）——支持MCP的重构版本待发布
将已保存的Workflow作为分析工具运行	MCP（当Workflow注册为MCP工具时，每个账户动态配置）	由宿主工具列表临时覆盖——暂无专用技能
地理空间模式分析（热点分析、GWR、空间自相关等）	CLI（Workflows）	`carto-pattern-*` 系列技能

How to detect what's available

如何检测可用路径

What	How
CARTO CLI installed	`carto --version` succeeds in a shell.
CARTO MCP server attached	Tools named `view_map` , `load_builder_map` , `list_maps` , `list_connections` , `search_resources` , `get_column_stats` appear in your tool list.
MCP host renders MCP Apps (interactive widgets)	Claude.ai, Claude Desktop, ChatGPT do. Gemini CLI, Codex CLI, plain MCP Inspector, current MCPJam do not — those execute MCP tools but show only text confirmations, no inline widget.

If an MCP-route intent is asked but the MCP server isn't attached (or the host doesn't render MCP Apps for visualization), surface that to the user — don't silently fall back to a generic visualization widget or a hand-rolled HTML map.

检测对象	检测方法
已安装CARTO CLI	在shell中执行 `carto --version` 命令成功返回结果。
已连接CARTO MCP服务器	工具列表中出现 `view_map` 、 `load_builder_map` 、 `list_maps` 、 `list_connections` 、 `search_resources` 、 `get_column_stats` 等工具。
MCP宿主支持渲染MCP Apps（交互式组件）	Claude.ai、Claude Desktop、ChatGPT支持。Gemini CLI、Codex CLI、普通MCP Inspector、当前版本MCPJam不支持——这些工具可执行MCP命令，但仅显示文本确认信息，无法内联渲染组件。

如果用户提出需要通过MCP路径处理的需求，但未连接MCP服务器（或宿主不支持渲染MCP Apps进行可视化），请向用户说明情况——不要默认回退到通用可视化组件或手动编写的HTML地图。

Why this orientation lives here

为何此处提供路径说明

The catalog's existing CLI-action skills (

carto-explore-datawarehouse

carto-query-datawarehouse

carto-create-workflow

, etc.) are CLI-only today. As they become mode-aware (per-skill MCP/CLI routing internal to each skill), this orientation table will narrow — eventually each skill picks its own access path internally and

carto-basics

carries only the meta-orientation. Until then, this section is the routing source of truth.

目录中现有的CLI操作技能（

carto-explore-datawarehouse

、

carto-query-datawarehouse

、

carto-create-workflow

等）目前仅支持CLI。当这些技能实现模式感知（每个技能内部支持MCP/CLI路由）后，本说明表格的范围会缩小——最终每个技能会自行选择访问路径，而

carto-basics

仅保留元导向内容。在此之前，本部分是路由的权威参考。

Always-on guidance

始终遵循的指导建议

Always pass
--json
when you need machine-readable output. CLI text output is for humans and may change.
Map URLs use the tenant domain from
```
auth status
```
, not a generic workspace URL. Private maps live at
```
https://{tenant_domain}/builder/{map_id}
```
; public/shared maps at
```
https://{tenant_domain}/map/{map_id}
```
. Never construct
```
workspace-{region}.app.carto.com
```
URLs.
Confirmation prompts: destructive commands like
```
maps delete
```
prompt for the literal word "delete". Pass
```
--yes
```
(or
```
--json
```
) for non-interactive use.
Async jobs:
```
imports create
```
and
```
sql job
```
poll until completion by default. Pass
```
--async
```
(where supported) to return immediately and poll separately.

始终传递
--json
参数：当你需要机器可读的输出时，请使用该参数。CLI的文本输出是面向人类的，可能会发生变化。
地图URL：使用
```
auth status
```
返回的租户域名，而非通用工作区URL。私有地图的地址为
```
https://{tenant_domain}/builder/{map_id}
```
；公开/共享地图的地址为
```
https://{tenant_domain}/map/{map_id}
```
。切勿构造
```
workspace-{region}.app.carto.com
```
格式的URL。
确认提示：像
```
maps delete
```
这类破坏性命令会要求输入确切的单词"delete"进行确认。在非交互式使用场景下，传递
```
--yes
```
（或
```
--json
```
）参数跳过提示。
异步作业：默认情况下，
```
imports create
```
和
```
sql job
```
会轮询直到作业完成。若需要立即返回结果并单独轮询，请在支持的命令中传递
```
--async
```
参数。