motherduck-cli

使用 MotherDuck CLI

事实依据

• 优先参考最新的 MotherDuck CLI 文档和命令参考。依赖记忆中的标志之前，先查看命令帮助，因为命令接口可能会变化。
• 创建或编辑 Dive 或 Flight 之前，先运行 motherduck dive guide 或 motherduck flight guide。这些内置指南是当前运行时的约定。
• 遇到解析或选项错误后，使用 motherduck <command> --help，不要猜测语法。

默认做法

• 如果已有经过身份验证的 CLI，请重复使用；开始登录流程前先用 motherduck status 检查。
• 对于自动化任务，通过环境传递 MOTHERDUCK_TOKEN，并设置绝对路径、任务专用的 MOTHERDUCK_HOME，以免并行 Agent 共用凭据或资源。
• 对于机器可读的资源操作，请求 --output json，并检查退出代码和返回的 success 字段。motherduck query --output json 则会返回一个裸 JSON 数组。
• 大型查询结果应重定向到文件，而不是将所有行都拉入模型上下文。
• 切勿仅因缺少身份验证就运行 motherduck new。创建账户需要明确的注册请求。
• 使用 motherduck guide init|pull|push 将 Guides 保留为文件；push 会创建或更新内容，且只有在内容发生变化时才会新增版本。使用 --external-id 记录 Git SHA，并使用 --version-description 说明原因。pull 会覆盖本地文件，因此请先推送或保存本地修改。
• 将 dive push、flight push、guide push、计划任务、密钥变更和账户创建视为外部变更。只有当用户的构建／变更请求明确包含这些操作时才执行。

工作流

1. 检查宿主项目以及现有 CLI／身份验证状态。
2. 仅在需要时安装或升级，并遵循当前的平台专属文档。
3. 根据任务类型选择 CLI 或 MCP：
   • 文件、本地编辑、CI、大型结果或反复迭代：CLI
   • 仅限聊天的探索、内联回答或没有文件系统：MCP
   • 混合工作流：通过 MCP 探索，然后使用 CLI 从本地文件构建
4. 对于查询，使用 motherduck query，并选择足以满足需求的最小输出格式。
5. 对于 Dive 或 Flight，先阅读其内置指南，拉取或初始化本地项目，编辑文件，验证或预览，然后仅在请求发布时推送。
6. 从 JSON 输出中记录资源 ID、URL 或运行编号，并在变更后验证远程状态。

对于回答、审查或规划请求，应推荐命令，但不要登录、创建账户或更改远程资源。对于明确的构建／变更请求，应完成范围内的 CLI 工作流并验证结果；进行破坏性删除或范围明显更广的外部变更前，应先询问。

参考资料

只阅读当前任务所需的参考资料章节。

• 阅读 references/CLI_PLAYBOOK.md，了解安装、身份验证、JSON 协定、查询模式、Agent 隔离以及完整的 Dive／Flight 文件工作流。

相关技能

仅在缺少相应能力时加载相关技能；重复使用已有上下文。

• motherduck-connect：选择底层应用连接方式
• motherduck-explore 和 motherduck-query：发现目录并了解 SQL 行为
• motherduck-create-dive 和 motherduck-create-flight：了解特定产品的创作工作流