datocms-cli

DatoCMS CLI 技能

用于 CLI 命令、迁移和本地项目配置。

纯粹的结构化文本转换或本地 DAST 工作 → 在 CLI 引导前使用 datocms-structured-text：文档模型、编辑或转换。需要执行项目操作时，CLI 执行/身份验证仍在此处处理。缺少同级参考文件 → 从 datocms/agent-skills 安装该技能，或更新完整技能包；普通 CLI 命令不需要这些文件。

步骤 1：检测上下文

沿用已建立的 CLI 上下文。对于实时读取或内容操作，先遵循 datocms-cma 路由选择。不要仅为取代当前可用的远程 MCP 连接而安装 CLI。用户选择使用 DatoCMS MCP 进行实时操作 → 在用户明确切换前，到此为止并继续使用它。

仅在选择执行 CLI 时进行引导；解释命令不需要连接。CLI 专属的迁移、关联、配置文件、导入和类型生成都在此处处理。

检测（不要依赖 which datocms — CLI 通过 npx 运行）

1. package.json 的 devDependencies 中有 datocms → CLI 可用。若选择执行 CLI 但缺少该依赖：安装它（npm install --save-dev datocms）。
2. 当前配置文件中，datocms.config.json 含有 siteId → 已关联。尚未关联 + 已设置配置文件令牌环境变量（默认为 DATOCMS_API_TOKEN；.env/.env.local 也算）→ 令牌身份验证可用：跳过 login/projects:list/关联（关联会覆盖该设置）。否则按以下流程引导。
3. npx datocms whoami 成功 → OAuth 会话已激活。
4. 存在 migrations/ 目录 → 迁移脚手架已搭建。
5. 存在 tsconfig.json 或 migrations.tsconfig → 使用 TypeScript 迁移约定。

引导流程（CLI 可用但尚未关联）

只有 datocms login 需要终端；其余操作在非 TTY 环境中运行。

npx datocms login  # user, one-time, interactive
npx datocms projects:list [hint] --json # agent discovers siteId
npx datocms link --site-id=<ID> [--organization-id=<ID>] # agent links

运行 datocms link 前，务必先与用户确认目标项目，即使 projects:list 只返回一个候选项目也是如此。展示候选项目（名称、id、组织）并等待用户明确同意。不要把“只有一个结果”视为同意 — 用户可能有权访问某个项目，但并不打算将此仓库关联到该项目；之后修复错误关联会很麻烦。

不带 --site-id 运行 datocms link 需要终端。在非 TTY 环境中，它现在会正常退出并提示传入 --site-id；不要不带该参数重试。凭据缺失时也一样 — 请先让用户运行 datocms login。

执行 CLI 工作时，在编写依赖架构的代码或进行变更前，先对选定的项目/环境运行 npx datocms schema:inspect（不要手动拼接模型和字段调用）。按需使用模型 API key、id 或名称进行筛选。参见 references/schema-inspect.md。

身份验证策略

• 交互式 CLI 执行：通过 login + link 使用 OAuth。此情况下，绝不要要求用户粘贴令牌，也不要让用户将 DATOCMS_CMA_TOKEN=... 添加到 .env。
• 无人值守执行（CI、cron、服务端应用、没有 OAuth 会话的共享脚本）：通过环境变量使用启用了 CMA 的令牌。只读 CDA 令牌（DATOCMS_PUBLISHED_CONTENT_CDA_TOKEN、DATOCMS_DRAFT_CONTENT_CDA_TOKEN、NEXT_PUBLIC_DATOCMS_API_TOKEN）无法使用 — 请指出需要单独的 CMA 令牌。

步骤 2：确定工作流

不要仅因类别显而易见就跳过提问。只有在请求已包含相关类别的关键输入，或检查仓库后能够安全地确定答案时，才跳过后续问题。

提出最少且有针对性的问题，以免抹去实际工作流选择。

各类别的输入位于参考文件中

每份类别参考文件在步骤 3 加载时，都会以**“运行命令前需确认的输入”**部分开头 — 这相当于本步骤针对各类别的说明。不要跳过与任务类别对应的参考文件加载：其中包含本步骤旨在保护的工作流决策。跳过加载就等于跳过检查清单。

架构变更——与用户确定处理方式

如果根据请求无法明确判断应采用哪种方式，请询问用户——可逆性和工作流偏好比用哪个工具执行变更更重要。

任务	处理方式
破坏性架构变更：删除字段或模型、对记录执行 bulk_destroy、有损的 field_type 变更（例如 string → json；任何会丢弃已存储值的变更）	先针对分叉的沙箱使用迁移（migrations:new）。未经用户明确且重复确认，绝不能针对主环境执行。
可逆的架构变更：添加字段／模型／区块、重命名字段、切换 required、添加／收紧验证规则、重新排列字段集	询问 "你希望将其作为可审核的迁移，还是直接在沙箱中修改？"——由用户的回答决定采用哪种方式，而不是首次加载的技能。如果仓库使用迁移，或用户正在次要分支上工作，优先选择迁移；快速迭代沙箱时也可以直接修改。仅当用户没有偏好且仓库中有迁移惯例（migrations/ 目录、先前的迁移提交）时，默认选择迁移。
明确要求一次性操作或选择退出（"直接修补即可"、"不走迁移工作流"、"不要搭建迁移"）	遵从直接修改。除非变更后来发现具有破坏性，否则不要重新建议迁移。
内容操作：发布／取消发布、删除单条记录、修正别名、批量更新字段值、重新标记上传内容	无需迁移。
需要提交代码并在不同环境中重放	使用迁移，而不是 datocms-cma。

破坏性变更和迁移分支留在此处：加载 creating-migrations.md + running-migrations.md。一次性操作、内容操作、直接修改分支 → datocms-cma：由它负责 API 操作并选择执行方式（CLI cma:call／cma:script，或 MCP）；请自行加载其参考资料，不要让用户来回切换。命令机制保留在此处——cma:call／cma:script／cma:docs 标志、标准输入与文件模式、环境级全局变量、环境目标设置（direct-cma-calls.md、cma-script.md）。已签入的 buildClient() 脚本和无人值守的运行时代码（CI、应用服务器、Webhook、长期运行的自动化）→ datocms-cma。

破坏性操作和生产环境敏感操作的确认

破坏性架构变更始终需要以下确认；下方列表也涵盖非架构类破坏性命令。

如果缺少相关上下文，在提供最终命令前，请先征求用户的明确确认：

• environments:destroy
• environments:promote
• 导入到无法明确判断为可随时销毁的目标环境
• 在类似主环境的环境上执行 migrations:run --in-place（在主环境上执行 --in-place --allow-primary）
• maintenance:on --force
• environments:fork --fast --force
• 使用 destroy、bulk_destroy 或 promote 方法的 cma:call
• 通过 cma:call 或 cma:script 直接修改架构，并针对类似主环境的环境执行，而非在分叉的沙箱上使用迁移
• plugins:reset（移除所有用户安装和关联的 CLI 插件）

步骤 3：加载参考资料

根据任务分类，从此技能文件旁边的 references/ 目录读取相应的参考文件。只加载相关内容。

仅在需要设置或配置时加载：

• references/cli-setup.md — 安装、配置、配置档案、全局标志、令牌解析

按类别加载：

任务类别	参考文件
创建迁移	references/creating-migrations.md
运行迁移	references/running-migrations.md
生成架构	references/schema-generate.md
检查架构	references/schema-inspect.md
直接调用 CMA 的机制	references/direct-cma-calls.md（用于 cma:call）和／或 references/cma-script.md（用于 cma:script）
环境管理	references/environment-commands.md
部署工作流	references/deployment-workflow.md
多项目同步	references/blueprint-sync.md
导入内容	references/importing-content.md
CLI 插件管理	references/cli-plugin-management.md

需要复制到仓库中的捆绑辅助文件：scripts/（发布和多项目同步包装脚本）以及 assets/（对应的 GitHub Actions 工作流）；相关约定见 deployment-workflow.md › Release Helper 和 blueprint-sync.md › Automation Guidance。

根据需要加载跨领域参考资料：

• 如果同时创建和运行迁移 -> 加载 creating-migrations.md 和 running-migrations
• 如果生成架构后需要修改使用类型化 CMA 的代码 -> 另行加载使用生成类型的 datocms-cma 指南
• 如果直接调用 CMA 的操作不再是一次性命令 -> 改用 datocms-cma 编写可复用代码
• 如果部署涉及环境命令 -> 另行加载 environment-commands.md
• 如果多项目同步涉及执行部署 -> 另行加载 running-migrations.md
• 如果安装 CLI 插件是专门为了导入 WordPress／Contentful -> 另行加载 importing-content.md

步骤 4：实施并验证

使用所选参考资料了解命令语法、必需输入、模板和验证方式。保留仓库使用的包管理器运行器；否则使用 npx datocms。

• 使用 migrations:new 创建迁移脚手架，不要手动命名文件。使用参考资料中的准确函数签名；在函数体中调用 API 时加载 datocms-cma。
• 对于迁移，指定 --source，先进行试运行，并优先选择分叉后运行，而非在主环境中使用 --in-place。将 --force 视为明确的覆盖选项。
• 对于直接调用，在选择位置参数、stdin 或文件模式之前，先加载 direct-cma-calls.md 或 cma-script.md。沿用步骤 2 中确定的架构方案和环境授权方式。
• 执行前，验证所选的身份验证路径、配置档案、环境和输出路径。沿用现有的 OAuth 或无人值守令牌身份验证方式；不要求两者同时具备。
• 验证请求的结果，并报告运行了什么、检查了什么，以及有哪些尚未解决的输入。对于命令示例，说明缺少的前置条件，不要连接。

跨技能路由

此技能涵盖 CLI 命令、标志、配置、工作流和迁移文件脚手架。如果任务涉及以下任何内容，请启用配套技能：

条件	路由至
脚本或迁移中的 DAST	datocms-structured-text；记录持久化请使用 datocms-cma
迁移脚本正文中的 CMA API 调用（记录、架构、上传）	datocms-cma
在代码中通过 client.environments.* 以编程方式管理环境	datocms-cma
在应用代码或可复用脚本中使用生成的架构类型	datocms-cma
使用 GraphQL 查询内容以供前端展示	datocms-cda
设置框架集成、草稿模式或实时更新	datocms-frontend-integrations
构建 DatoCMS 插件	datocms-plugin
用户希望规划或逐步完成设置（迁移加发布、多项目同步、将内容导入项目）	datocms-setup