fix(carto-basics): drive CLI install + headless auth in sandboxes (sc-552958)#49
Merged
ernesmb merged 3 commits intoJun 29, 2026
Conversation
…-552958)
In ephemeral agent sandboxes (e.g. Claude Code Cowork tasks) the CARTO CLI
is wiped per task and the default npm global prefix is unwritable, so agents
dead-ended at execution: they deflected ("run it on your own machine"),
silently degraded to Python/SQL/deck.gl, or waited on a browser OAuth that
never completes. The skill led with the local happy path and gave no recovery.
- SKILL.md: replace local-only "Quick start" with an environment-aware
Preflight (check -> tell-then-do install -> auth status -> headless login),
re-run each task; add a "Never silently degrade" rule to always-on guidance.
- installation.md: document the EACCES / `--prefix ~/.npm-global` + PATH
fallback and per-task reinstall reality.
- authentication.md: make `--no-launch-browser` the documented agent default
(an agent can't drive a browser OAuth) and prohibit substituting an
M2M / API token for headless login.
- Move the CLI-vs-MCP access-paths orientation into references/access-paths.md
(keeps SKILL.md under the ~5KB budget) and record CLI-ephemeral vs
MCP-persistent in sandboxes.
No detection heuristics: relies only on deterministic signals (command exit
codes, EACCES-then-retry) plus headless-by-default, which degrades gracefully
everywhere.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
srtena
requested changes
Jun 25, 2026
| | 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 | |
Contributor
There was a problem hiding this comment.
Are you sure about exposing "refactor pending" stuff? Feels very internal
Contributor
Author
There was a problem hiding this comment.
Agreed, that's internal roadmap leaking into shipped docs. Stripped "— MCP-aware refactor pending" from all three rows, and removed the "Why this orientation lives here" note below for the same reason (it carried the same internal voice and was redundant with the "CLI today" column). (fb11713)
- carto-develop-app row: note the CLI mints/manages the app's credentials
and tokens, rather than implying developer code is the only touchpoint.
- Drop internal-roadmap language ("MCP-aware refactor pending") from the
routing rows and remove the "Why this orientation lives here" note that
carried the same internal voice — the "CLI today" column already conveys it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
srtena
approved these changes
Jun 26, 2026
ernesmb
deleted the
bug/sc-552958/-internal-carto-basics-skill-cli-not-installed
branch
June 29, 2026 09:04
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
sc-552958 — in ephemeral agent sandboxes (e.g. Claude Code Cowork tasks), the CARTO CLI is wiped per task and the default npm global prefix is unwritable. With the skills installed and firing, the agent still dead-ended at execution: it deflected ("run it on your own machine"), silently degraded to Python/SQL/deck.gl, or waited on a browser OAuth that never completes.
The team's investigation (Kevin Thomson on the story) corrected two claims in the original report and is the basis for this fix:
What changed (carto-basics only — downstream skills already defer here)
SKILL.md— replaced the local-only "Quick start" with an environment-aware Preflight:carto --version→ tell-then-do install →carto auth status→ headless login; re-run each task. Added a "Never silently degrade" rule to always-on guidance.references/installation.md— documented theEACCES→--prefix ~/.npm-global+ PATH fallback and the per-task reinstall reality.references/authentication.md— made--no-launch-browserthe documented agent default (an agent can't drive a browser OAuth; plain login hangs on a localhost callback), and prohibited substituting an M2M/API token for headless login.references/access-paths.md(new) — moved the CLI-vs-MCP orientation block out ofSKILL.mdso it lands under the ~5KB budget (4925 B); records CLI-ephemeral vs MCP-persistent in sandboxes.Design note
No environment sniffing — that's unreliable and host-specific (the skill runs in Claude Code / Codex / Gemini). The fix relies only on deterministic signals (command exit codes,
EACCES-then-retry) plus headless-by-default, which degrades gracefully on a laptop too.Validation
make validategreen — 23 skills, 521 snippets.make syncproduced no manifest changes (catalog.json untouched; discovery already works).🤖 Generated with Claude Code