Cloudeval AI

Cloudeval CLI

在终端中掌控你的云：评估、报告，并为 Agent 做好准备。

Cloudeval CLI 可将 ARM 模板、托管在 GitHub 上的 IaC 和 实时 Azure 上下文转化为成本、架构和 Well-Architected 信号。你可以将其用作终端 UI、可编写脚本的自动化客户端，或供 Codex、Cursor、Claude、VS Code 及任何 stdio JSON-RPC 客户端使用的 MCP 服务。

为什么使用它

安装

Node.js 20+ 用户可以从 npm 安装：

npm install -g @ganakailabs/cloudeval-cli
cloudeval --help

macOS、Linux、WSL2、Git Bash，以及 Windows 或 Linux 上的 PowerShell 7+ 用户可以使用独立版本安装程序：

curl -fsSL https://cli.cloudeval.ai/install.sh | bash

irm https://cli.cloudeval.ai/install.ps1 | iex

然后重新加载 shell 并登录：

source ~/.bashrc   # or: source ~/.zshrc
cloudeval login
cloudeval status
cloudeval chat

设备登录会通过 cloudeval.ai 进行，并始终要求浏览器身份验证提供方显示账户选择器，以便用户选择预期的工作邮箱，即使已有其他账户登录也不例外。正常使用 CLI 无需注册本地 Azure 应用。

curl -fsSL https://cli.cloudeval.ai/install.sh | CLOUDEVAL_INSTALL_AGENT_SETUP=0 bash
curl -fsSL https://cli.cloudeval.ai/install.sh | CLOUDEVAL_INSTALL_MCP_CLIENTS=codex,cursor bash
curl -fsSL https://cli.cloudeval.ai/install.sh | CLOUDEVAL_TELEMETRY=0 bash

$env:CLOUDEVAL_ASSUME_YES = "1"
irm https://cli.cloudeval.ai/install.ps1 | iex

遥测

Cloudeval CLI 默认会向 Azure Application Insights 发送经过筛选的自定义事件。事件涵盖命令类别、成功状态、耗时、安全选项枚举值、CLI 版本、Node/运行时版本、OS 主版本、架构、安装来源、更新/安装结果、MCP 工具名称，以及 TUI 启动/退出元数据。登录后，事件可能包含已登录用户的邮箱、名和姓或全名。

遥测绝不会发送原始提示词、命令输出、令牌、本地路径、项目或资源标识符、账户/会话/租户标识符、云资源名称、堆栈跟踪或原始错误消息。可随时禁用或重新启用：

cloudeval config set telemetry.enabled false
cloudeval config get telemetry.enabled --format json
cloudeval config set telemetry.enabled true
cloudeval config unset telemetry.enabled

单次运行时，环境变量覆盖优先级更高：

CLOUDEVAL_TELEMETRY=0 cloudeval status --format json
CLOUDEVAL_TELEMETRY=1 cloudeval --help

之后更新：

cloudeval update --check
cloudeval update --yes

更新后，在准备加载新公开的 Cloudeval 工具、资源或提示词时，重启或重新加载已配置的 MCP 客户端。Cloudeval 不会自动重启 Codex、Claude、Cursor、VS Code 或其他 MCP 宿主。

卸载由本地安装程序管理的构件，同时默认保留 Cloudeval 配置、会话和身份验证：

cloudeval uninstall --dry-run
cloudeval uninstall --yes
cloudeval uninstall --yes --remove-config  # also removes ~/.config/cloudeval
npm uninstall -g @ganakailabs/cloudeval-cli # if installed through npm

从这里开始

cloudeval                         # Terminal UI
cloudeval tui --graph-diagram ascii
cloudeval ask "Summarize my cloud risk" --format json
cloudeval agent "Find cost and architecture risks" --format json
cloudeval agents list
cloudeval agents run cost --project <project-id> --format json
cloudeval recipes list
cloudeval projects list
cloudeval uninstall --dry-run
cloudeval projects graph insights <project-id> --focus impact --resource <resource-id> --format json
cloudeval validate template --template-file template.json --parameters-file parameters.json --rule <check-id> --details --wait --progress stderr --wait-timeout 600000 --format json
cloudeval validate tests --template-file template.json --parameters-file parameters.json --wait --progress stderr --wait-timeout 600000 --format json
cloudeval rules search "public network" --format json
cloudeval reports list
cloudeval actions list --type architecture,cost,unit-tests --format json
cloudeval actions open --print-url --no-open
cloudeval review --repo owner/repo --ref feature/infra-change --commit-sha <sha> --github-checks --sarif --output cloudeval-review --format json --non-interactive
cloudeval capabilities --format json
cloudeval doctor --deep

完整文档：CLI 入门和 CLI 命令参考。

在终端 UI 中，使用 Thread 控件或 /thread，即可切换已打开的聊天 会话、最近的 Cloudeval 聊天线程和本地 CLI 会话。/thread new 会启动另一个独立的已打开会话；如果当前会话有线程 ID，/open 会跳转到 Cloudeval 中的同一聊天 线程。较宽的终端会显示包含项目、线程、模型、模式、配置文件和报告构件 标签的上下文栏；较窄的终端则优先显示 聊天，并通过输入框和斜杠命令提供相同的控件。 输入 / 会打开底部的命令补全栏；使用 Tab 或上/下方向键移动， 按右方向键接受灰色提示文本，按 Enter 选择高亮的命令。 流式任务会在会话线程中显示为任务清单，底部输入框 会固定停靠，以免输入提示词时与对话记录争抢空间。带有依据的 回答会显示编号引文和“来源”部分，而不是原始的 [S_tool_...] 标签，并在行内高亮引文编号；/copy 会复制 最新的助手回复，/download 会将带有相同引用的 Markdown 对话记录写入文件。图谱洞察 块会呈现为带边框的终端卡片，而不是显示原始的 graph-insight 标记；如果卡片包含 保守的 Mermaid 流程图，--graph-diagram auto 会在较宽的 TTY 中渲染终端 图表，unicode 或 ascii 可强制指定模式，而 off 会保留 Mermaid 源码作为回退。无法支持的 Mermaid 语法会以源码形式显示， 而不会破坏对话记录。协商生成的聊天可视化内容会直接在 TUI 中渲染： 折线图/面积图趋势使用 Unicode 图表；条形图、柱状图、直方图、饼图、圆环图、 雷达图和极坐标数据使用适应宽度的条形图；散点图和热力图数据使用紧凑的 终端网格；不支持的图表类型使用构件中的表格作为回退。 Mermaid 流程边会渲染为边列表；如果无法提取边，则使用有限长度的 Mermaid 源码作为 回退。HITL 审批提示要求明确选择一个选项或输入答案；在空白审批提示中按 Enter 不会选择推荐选项。项目和连接选项卡会显示所选项目的详细信息窗格，包括后端字段、报告覆盖范围、同步状态和 关联记录；在“项目”和“连接”中，使用 J/K 或上/下方向键移动 所选行，然后按 Enter 确认。计费栏会分别显示剩余点数和已观察到的 已用点数，避免让用量看起来像当前预算。使用“配置文件” 控件或 /profile cost，通过 Agent 配置文件运行当前提示词； 选择配置文件会将 TUI 切换到 Agent 模式，选择“询问”模式 则会清除配置文件，恢复默认聊天流程。只有运行 /starter 后才会显示入门提示词。按提示词输入框中的 Esc 可退出文本编辑状态，这样 Tab、方向键和数字快捷键便可用于浏览控件和选项卡；再次输入即可 恢复编辑。可通过 --no-anim 禁用忙碌加载动画和输入光标。横幅详情 包含已登录用户。获得焦点的控件和当前顶部选项卡使用统一的暖黄色横幅强调色， 当前选项卡的填充色会覆盖整个按钮内部区域。

CLI 会在聊天请求中声明 cloudeval.visualization/v1、flint-v1 和 mermaid-v11 功能。后端会编译图表意图； CLI 会验证有限制的构件，并渲染适用于终端的输出，无需 浏览器或原生 SVG 辅助工具。ask 和 agent 的 JSON 结果在存在可视化内容时会包含 data.visualizations；NDJSON 除了在最终的 result 中包含这些构件外，也会发出 visualization 事件。即使流式文本省略或损坏图表内容，最终 JSON/NDJSON 响应、 Markdown 输出和本地对话历史仍会保留经过验证的构件围栏。 文本输出仍是实时文本流。请参阅 可视化构件规范。

核心工作流

Agent 配置文件 ID 包括 architecture、cost、triage、remediation、 visual-explainer、scripter、change-reviewer、evidence-auditor 和 security-reviewer。显示名称可能包含空格。Architecture 配置文件 包含 Well-Architected 评审视角，因此没有单独的 Well-Architected Agent 配置文件。当 agents run 未提供提示词时，CLI 会根据所选项目源和配置文件模式使用起始提示词：模板或实时同步、ask 或 agent。此选择在自动化中具有确定性。配置文件运行只发送 agent_profile_id；Cloudeval 会在后端应用配置文件指令、规划视角和 响应默认设置。agents list 和 agents show 会先尝试 后端配置文件目录；如果配置文件目录端点要求登录或 不可用，则会回退到捆绑的公开目录，确保发现功能仍可用。agents run 仍需要经过身份验证的后端访问权限。在 TUI 中， 配置文件选择器使用相同的规范 ID，并在聊天流中发送选定的 agent_profile_id。

运行 cloudeval <command> --help 查看确切的标志。

CI 和 Agent 的访问密钥

人类用户请使用 cloudeval login。浏览器授权页面会在每次登录时请求选择账户。对于 CI、托管式 Agent 和长时间运行的自动化任务，请使用限定范围的访问密钥。

已存储的设备登录会话会在经过身份验证的请求发出前自动刷新。如果 TUI 或 cloudeval ask 从聊天流收到令牌过期响应，CLI 会刷新已存储的会话，并重试该请求一次。如果刷新令牌已被撤销或过期，请重新运行 cloudeval login。

登录并选择项目后，创建访问密钥：

cloudeval projects list
cloudeval credentials templates --format json
cloudeval credentials create \
  --template ci \
  --name github-actions-prod \
  --project <project-id> \
  --expires 90d \
  --idempotency-key "$(uuidgen)" \
  --format github-actions

--format github-actions 会显示一次 CLOUDEVAL_ACCESS_KEY 和 CLOUDEVAL_PROJECT_ID。credentials list 或 credentials inspect 不会再次显示原始密钥。

在不将限定范围的访问密钥写入 Shell 历史记录的情况下进行测试：

printf '%s\n' "$CLOUDEVAL_ACCESS_KEY" | cloudeval projects list \
  --access-key-stdin \
  --format json \
  --non-interactive

凭据规则：

• 优先使用 --access-key-stdin 或 CLOUDEVAL_ACCESS_KEY；
• 可以使用 --access-key，但会发出警告，因为进程参数和 Shell 历史记录可能导致密钥泄露；
• 旧版 Beta 名称 --api-key、--api-key-stdin 和 CLOUDEVAL_API_KEY 会因迁移错误而失效；
• 默认会对访问密钥格式的字符串、授权标头和敏感 URL 查询参数进行脱敏；
• 在 POSIX 系统上，凭据创建操作生成的输出文件会使用私有权限。

面向编码 Agent 的 MCP

登录后启动 MCP，或者在宿主环境中提供限定范围的 CLOUDEVAL_ACCESS_KEY：

cloudeval login
cloudeval mcp serve
cloudeval mcp serve --toolset readonly

客户端配置示例：

codex mcp add cloudeval -- cloudeval mcp serve --toolset readonly
cloudeval mcp setup cursor --dry-run --toolset reports --format json
cloudeval mcp setup vscode --dry-run --toolset readonly --format json

MCP 规则：

• 工具名称使用下划线，例如 projects_list、recipes_list 和 billing_summary；
• 带点号的工具名称仍作为兼容别名保留；
• 标准输出仅包含 JSON-RPC，[cloudeval-mcp] 诊断信息会输出到标准错误；
• MCP 工具架构不接受每次调用单独传入访问密钥；
• mcp serve 不支持 --access-key-stdin，因为标准输入是协议流；
• readonly 包含用于安全检查项目、报告、账单、连接、凭据、配置、模型、会话、身份验证、状态、诊断和配方的工具；生成、下载、检出、凭据修改、打开浏览器和写入图表文件等操作仍需显式启用。

查看账单时，使用 billing_ledger 查看单笔用量尝试和额度扣费，使用 billing_usage 查看汇总数据，使用 billing_summary 查看当前权益。账本筛选条件默认覆盖 30 个日历日；startAt 和 endAt 分别覆盖对应的日期范围边界。当 data.has_more 为 true 时，将 data.next_cursor 作为 cursor 参数传入，并保持筛选条件不变。账本每页默认包含 25 条记录，范围限制为 1–100 条。

billing_invoices 会返回订阅发票、已支付的充值历史记录和账单周期状态。获取这些数据可能会为已支付的充值创建缺失的服务提供商发票记录，并保存收据链接。因此，必须显式选择 --toolset billing 或 --toolset all，且此工具不包含在 readonly 中。结果数量限制默认值为 25，每个集合限制为 1–50 条，且没有分页游标。这些工具需要通过服务端配置的凭据获得账单读取权限；它们不会发起购买或更改订阅。

开发者设置详情：cli.cloudeval.ai/developer/。

Recipes And Skills

Cloudeval recipes 是供 Agent 和用户复用的工作流。当前 recipes 涵盖成本审查、WAF 分流、架构审查、模板项目审查、报告摘要、报告生成规划、报告导出包、账单审查、充值准备情况、项目清单与健康检查、连接审计、凭据设置与轮换、模型选择、会话恢复、CLI 入门检查、前端工作区链接、架构／依赖关系图导出，以及 MCP 设置。

cloudeval recipes list
cloudeval recipes show cloudeval-cloud-cost-review
cloudeval recipes run cloudeval-cloud-cost-review --project <project-id> --format json --non-interactive
cloudeval recipes show cloudeval-architecture-diagram-export
cloudeval recipes run cloudeval-dependency-diagram-export --project <project-id> --output-path ./dependency.svg

基于 ask/agent 的 recipes 可能会消耗模型额度。对于会创建项目、写入报告或图表文件、更改 MCP 配置、修改凭据、打开浏览器或启动结账流程的 recipes，系统会打印明确的命令，而不会隐式执行这些副作用。可移植的 Agent 指令位于 skills/ 下；对于 Codex、Cursor、Claude 和其他 Agent，MCP 仍是首选执行路径。

Project Example

curl -L -o template.json \
  https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.compute/1vm-2nics-2subnets-1vnet/azuredeploy.json

cloudeval projects create \
  --name "Azure VM network review" \
  --provider azure \
  --template-file ./template.json \
  --format json

如果不想使用本地文件，请使用 --template-url。根据需要，接着运行 reports run、reports download 和 projects export-diagram。

Output, Auth, And Privacy

cloudeval login
cloudeval login --headless
cloudeval auth status
cloudeval auth status --show-sensitive-ids
cloudeval help agents
cloudeval agents list

输出约定：

• cloudeval login 会打开或打印 cloudeval.ai/device/login 审批 URL，并附带面向 Web 身份验证提供方的账户选择器提示；
• 机器可读命令会将载荷写入 stdout；
• 提示、进度、浏览器打开消息和警告会写入 stderr；
• ask 和 agent 支持 --progress none、--quiet 或 --format ndjson --progress ndjson；
• validate template 和 validate tests 支持使用 --wait 时的 --progress stderr 或 --progress ndjson；验证进度始终写入 stderr，以便 stdout 上的最终 JSON/NDJSON 保持可解析。已完成的进度信息会包含失败检查／测试的详细信息，例如消息、建议、严重性，以及可用时的文件／模板或资源位置。如果已完成的后端结果仅包含工作进程本地临时文件路径，Cloudeval 会改为报告提交的模板文件名；
• 使用 --non-interactive 时，人工审批会以代码 6 退出，并返回 HITL_REQUIRED；
• 交互式 HITL 提示需要明确输入选项编号、是／否形式的回答或文本回复；直接按 Enter 不会批准推荐选项；
• --show-sensitive-ids 仅在可信机器上显示完整的账户／会话类 ID。它不会取消令牌的脱敏处理。

Docs

从源代码构建

在处理身份验证、凭据、冒烟测试产物或面向用户的命令行为之前，请先阅读 AGENTS.md。

git clone https://github.com/ganakailabs/cloudeval-cli.git
cd cloudeval-cli
pnpm install
pnpm build
pnpm -C packages/cli dev --help

为当前操作系统构建独立二进制文件：

pnpm --filter @ganakailabs/cloudeval-cli build:executable:current
./packages/cli/dist/bin/cloudeval --help

运行检查：

pnpm lint
pnpm test
pnpm test:npm-package
(cd packages/cli && npm pack --dry-run)
pnpm -C packages/cli test:cli:noninteractive
pnpm security:scan

社区

• Cloudeval 应用
• 文档
• 发布版本
• 问题
• Discord

许可证

Cloudeval CLI 是专有软件，依据 Cloudeval CLI 许可证 提供。 生产环境第三方软件包的归属信息记录在 THIRD_PARTY_NOTICES.md 中，发布版本的 SBOM 位于 sbom.spdx.json。已发布的安装程序也会将这些声明文件下载到 ~/.local/share/cloudeval/licenses。发布政策请参阅许可证合规。