# 为什么 AI 场景需要 CLI？
如今，AI Agent 已经进入软件研发流程。Zadig 官方 MCP Server 让支持 MCP 的客户端能够调用 Zadig，执行工作流、调整环境、修改配置和排查问题。
但不少 Agent 运行在终端、本地开发环境、CI 或自动化脚本中，对这些场景而言，命令行是更自然的入口。
Zadig CLI 进一步扩展了 Agent 使用 Zadig 的方式，为终端和自动化场景提供了更直接的执行入口。Agent 可以通过命令读取上下文、触发工作流、管理配置与资源，并执行受控操作。
简单来说：MCP 面向工具协议场景，CLI 面向终端与自动化场景，两者共同构成 AI Agent 使用 Zadig 的完整入口。
今天，Zadig CLI 正式发布！
在 Zadig CLI 的帮助下，一个 Agent 可以形成更完整的工作闭环：
读取 Zadig 中的真实上下文
基于项目、环境、服务、构建和工作流理解任务目标
给出下一步操作建议，或生成待执行的变更请求
用户确认后再执行真实操作
读取执行结果，完成验证
# 当前 CLI 支持的能力（持续更新中）
| 能力领域 | 当前支持 |
|---|---|
| 项目 | 创建、列表、详情、删除 |
| 服务 | 列表、详情、YAML 创建、配置更新、变量更新、删除 |
| 环境 | 创建、列表、详情、更新、删除、服务变更、Pod 查询、重启、日志 |
| 构建 | 创建、列表、详情、更新、删除 |
| 工作流 | 创建、列表、详情、更新、删除、执行、等待执行结果 |
| 工作流任务 | 列表、详情、取消、重试、审批、备注、日志 |
| 执行门禁 | 识别手动执行阶段、判断当前用户能否执行、继续执行 |
| 测试 | 执行测试任务、查询任务结果 |
| 代码扫描 | 执行扫描任务、查询任务结果 |
| 镜像仓库 | 列表、详情查询 |
| 集群 | 集群列表查询 |
| 用户 | 用户列表、详情、删除，用户组列表 |
| 权限 | 资源动作、角色 CRUD、用户及用户组角色绑定 |
| 操作日志 | 系统操作日志、环境操作日志 |
| Agent 集成 | Codex、Claude Code、Hermes Agent Skill |
| MCP 兼容 | 为 Cursor、VS Code 等客户端提供可选的只读 MCP 接入 |
| 自动化输出 | Table、JSON、Raw 输出，结构化错误和明确退出码 |
| 写操作保护 | --dry-run 预览、--yes 确认、本地请求审计 |
# 前置条件
Zadig 版本：请确保您的 Zadig 版本>= v5.0。
权限要求：需获取 Zadig 平台的 API Token（可在“账号设置”中获取）。
# 安装方法
# 一键安装 CLI 与 Skill
在终端（macOS / Linux / Windows）中执行：
npx -y @koderover/zadig-cli@latest install && zadig skill install
安装向导会完成以下操作：
将最新版 Zadig CLI 安装为全局命令
引导你输入 Zadig 服务地址和 API Token
保存本地凭据并检查连接状态
为检测到的 AI 编程工具安装 Zadig Skill
💡 Token 输入时不会明文显示，也不会写入 Skill 或客户端配置。
# 验证安装是否成功
查看 CLI 版本：
zadig version
检查 Zadig 连接状态：
zadig auth status --output json
检查本地安装和网络状态：
zadig doctor --output json
检查 AI Agent 是否已经识别 Zadig Skill：
zadig doctor agent codex --output json
zadig doctor agent claude-code --output json
zadig doctor agent hermes-agent --output json
安装或更新 Skill 后，需要重启对应的 AI 编程工具。
# 使用场景示例
以下是部分使用场景的演示，更多使用场景欢迎探索！
运维-实施阶段，基于一个已有项目复制新项目（包括服务、构建、环境及工作流）
运维-日常管理，批量清理无用工作流
研发-使用工作流更新服务
研发-查看服务日志并分析
研发-查看工作流构建日志分析效能瓶颈
# 常见问题
# 安装完成后提示`command not found` ？
Zadig Cli 通过 npm 安装到全局命令目录。请先查看 npm 的全局安装前缀，并确认终端能否找到 zadig：
npm prefix -g
command -v zadig
# 第一次使用需要做哪些配置？
推荐使用 setup 一次性完成凭据保存、Skill 安装和客户端配置：
zadig setup --host https://your-zadig.com --token <token>
配置完成后，需要重启 Codex、Claude Code、Cursor、VS Code 或 Hermes Agent。
# 如何确认 Zadig CLI 已经正确安装？
依次执行以下命令：
zadig version
zadig auth status --output json
zadig doctor --output json
doctor 会检查本地配置、凭据、网络连接和 Skill 安装状态，并为失败项提供处理建议。
# Token 从哪里获取？会被 AI Agent 读取吗？
Token 由用户从 Zadig 系统中获取，并在本地执行配置命令时输入。Zadig CLI 会将 Token 保存到本地凭据文件中，不会写入 Skill、MCP 配置或命令输出。
# 提示认证失败或 Token 无效？
重新配置当前 Profile：
zadig auth login \
--host https://your-zadig.com \
--token <token>
然后检查认证状态：
zadig auth check --output json
如仍然失败，请确认 Zadig 地址、Token 有效期以及当前网络是否能够访问 Zadig。
# AI 编码工具找不到 Zadig Skill ？
先重新安装 Skill：
zadig skill install
然后检查指定 Agent：
zadig doctor agent codex --output json
zadig doctor agent claude-code --output json
zadig doctor agent hermes-agent --output json
安装完成后需要重启对应的 AI 编码工具。
# 工作流执行后如何等待最终结果？
运行工作流时添加 --watch：
zadig workflow run <workflow-key> <project-key> \
--file <request.json> \
--yes \
--watch
只有工作流最终状态为 passed 时才返回退出码 0。失败、超时、取消或拒绝会返回非零退出码，可以在 CI 中据此判断执行结果。
# 加入 Zadig AI 进化营
欢迎体验 Zadig CLI，也欢迎把你在 AI 研发运维中的真实场景和反馈告诉我们。
我们会持续完善 CLI、MCP 与 Skill 能力，让 AI 不只理解研发，更能真正参与研发交付，让 Zadig 更自然地融入 AI Agent 工作流。
👉 扫码加入交流群（备注“Zadig CLI”），一起探索 AI + Zadig 的更多可能。
