# Carto Basics

> Start here for first-time CARTO use — install the CLI, authenticate, switch profiles, understand JSON output and async job patterns. Also orients on the two parallel access paths into the CARTO platform (CLI for authoring/scripting, MCP server for inline interactions in chat hosts) and which skills cover each.

- **Type:** Skill
- **Install:** `agentstack add skill-cartodb-agent-skills-carto-basics`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [CartoDB](https://agentstack.voostack.com/s/cartodb)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [CartoDB](https://github.com/CartoDB)
- **Source:** https://github.com/CartoDB/agent-skills/tree/master/skills/carto-basics

## Install

```sh
agentstack add skill-cartodb-agent-skills-carto-basics
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# carto-basics

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.

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

## Preflight — run before any CLI operation

Every CARTO skill assumes a working, authenticated `carto` CLI. Walk these checks before your first CLI call, and **re-run them at the start of each task** — ephemeral sandboxes (e.g. Claude Code Cowork tasks) wipe the CLI between tasks. An attached MCP server, by contrast, persists at the account level (see below).

1. **CLI present?** Run `carto --version`. If `command not found`, **install it yourself** — tell the user you're installing, then do it; never deflect with "run this on your own machine." The npm command plus the `EACCES` / writable-prefix fallback that sandboxes need are in [references/installation.md](references/installation.md).
2. **Authenticated?** Run `carto auth status`. If not, use the headless flow `carto auth login --no-launch-browser` — an agent can't complete a browser OAuth. **Never** open or wait on a browser, and **never** ask the user for an M2M / API token instead ([references/authentication.md](references/authentication.md)).

If install or auth can't complete, **say so and stop** — never silently fall back to Python / SQL / deck.gl or other non-CARTO tooling.

## What's in this skill

| Topic | Reference |
|---|---|
| Installing the CLI (npm, version verification) | [references/installation.md](references/installation.md) |
| Authentication: browser, headless `--no-launch-browser`, API tokens, SSO | [references/authentication.md](references/authentication.md) |
| Profiles: managing multiple orgs / environments | [references/profiles.md](references/profiles.md) |
| Global flags: `--json`, `--debug`, `--yes`, `--token`, `--base-url`, `--profile`, env vars | [references/global-options.md](references/global-options.md) |
| Access paths: CLI vs MCP routing, detection, host support | [references/access-paths.md](references/access-paths.md) |

## Access paths: CLI vs MCP server

The CLI and MCP server serve different intents — some flows chain across both. When an intent maps to MCP but the server isn't attached (or the host doesn't render MCP Apps), surface that; don't silently fall back to a hand-rolled map. The CLI is wiped per task in ephemeral sandboxes; an attached MCP server persists at the account level. Full routing table, detection signals, and host support: [references/access-paths.md](references/access-paths.md).

## Always-on guidance

- **Never silently degrade.** A CARTO request is answered with CARTO tooling. If the CLI can't be installed or authenticated (or a needed MCP route isn't attached), surface the blocker and stop — don't substitute Python, SQL, deck.gl, or other generic geospatial workarounds, and don't ask for an M2M token in place of `carto auth login --no-launch-browser`.
- **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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [CartoDB](https://github.com/CartoDB)
- **Source:** [CartoDB/agent-skills](https://github.com/CartoDB/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cartodb-agent-skills-carto-basics
- Seller: https://agentstack.voostack.com/s/cartodb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.