Cloudeval AI

Cloudeval CLI

Sua nuvem, no terminal: avaliada, reportada e pronta para agentes.

O Cloudeval CLI transforma modelos ARM, IaC hospedado no GitHub e contexto ao vivo do Azure em sinais de custo, arquitetura e Well-Architected. Use-o como uma interface de terminal, um cliente de automação com script ou um servidor MCP para Codex, Cursor, Claude, VS Code e qualquer cliente stdio JSON-RPC.

Por que usar

Instalação

Usuários com Node.js 20+ podem instalar pelo npm:

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

macOS, Linux, WSL2, Git Bash e PowerShell 7+ no Windows ou Linux podem usar o instalador de versão autônoma:

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

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

Em seguida, recarregue seu shell e faça login:

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

O login por dispositivo passa pelo cloudeval.ai e sempre solicita ao provedor de autenticação do navegador que mostre o seletor de contas, para que os usuários possam escolher o e-mail de trabalho pretendido mesmo quando outra conta já está conectada. Nenhum registro local de aplicativo Azure é necessário para o uso normal do CLI.

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

Telemetria

O Cloudeval CLI envia eventos personalizados selecionados ao Azure Application Insights por padrão. Os eventos cobrem família de comando, sucesso, duração, enums de opções seguras, versão do CLI, versão do Node/runtime, versão principal do SO, arquitetura, fonte de instalação, resultados de atualização/instalação, nomes de ferramentas MCP e metadados de inicialização/saída da TUI. Após o login, os eventos podem incluir o e-mail conectado e nome/sobrenome/nome completo.

A telemetria nunca envia prompts brutos, saída de comandos, tokens, caminhos locais, identificadores de projeto ou recurso, identificadores de conta/sessão/tenant, nomes de recursos de nuvem, stack traces ou mensagens de erro brutas. Desative ou reative a qualquer momento:

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

As substituições de ambiente têm precedência para uma única execução:

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

Atualize depois com:

cloudeval update --check
cloudeval update --yes

Após uma atualização, reinicie ou recarregue os clientes MCP configurados quando estiver pronto para carregar ferramentas, recursos ou prompts do Cloudeval recém-expostos. O Cloudeval não reinicia Codex, Claude, Cursor, VS Code ou outros hosts MCP automaticamente.

Desinstale artefatos de propriedade do instalador local mantendo a configuração, sessões e autenticação do Cloudeval por padrão:

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

Comece aqui

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

Documentação completa: Comece com o CLI e Referência de comandos do CLI.

Dentro da interface de terminal, use o controle de Thread ou /thread para alternar entre sessões de chat abertas, threads de chat recentes do Cloudeval e sessões locais do CLI. /thread new inicia outra sessão aberta independente, e /open salta para a mesma thread de chat no Cloudeval quando a sessão ativa tem um id de thread. Terminais espaçosos mostram uma trilha de contexto com chips de projeto, thread, modelo, modo, perfil e artefato de relatório; terminais mais estreitos mantêm o chat em primeiro lugar e expõem os mesmos controles através do compositor e comandos de barra. Digitar / abre uma faixa de conclusão de comando na parte inferior; use Tab ou Seta para cima/baixo para navegar, Seta para a direita para aceitar o texto fantasma e Enter para escolher o comando destacado. O trabalho em streaming aparece como um registro de tarefas na thread, e o compositor inferior permanece encaixado para que a entrada de prompt não compita com a transcrição. Respostas fundamentadas mostram citações numeradas e uma seção de Fontes em vez de tags brutas [S_tool_...], com números de citação destacados inline; /copy copia a resposta mais recente do assistente e /download grava uma transcrição em Markdown com as mesmas referências. Blocos de insights de gráfico são renderizados como cartões de terminal com borda em vez de expor marcadores brutos graph-insight; quando um cartão contém um fluxograma Mermaid conservador, --graph-diagram auto renderiza um diagrama de terminal em TTYs espaçosos, unicode ou ascii forçam um modo, e off mantém o fallback de fonte Mermaid. Sintaxe Mermaid não suportada permanece visível como fonte em vez de quebrar a transcrição. Visualizações de chat negociadas renderizam diretamente na TUI: tendências de linha/área usam gráficos Unicode; dados de barra, coluna, histograma, pizza, rosca, radar e polar usam barras cientes de largura; dados de dispersão e mapa de calor usam grades compactas de terminal; famílias de gráficos não suportadas usam o fallback de tabela do artefato. Arestas de fluxo Mermaid são renderizadas como uma lista de arestas, com fonte Mermaid limitada como fallback quando nenhuma aresta pode ser extraída. Prompts de aprovação HITL exigem uma seleção explícita de opção ou resposta digitada; pressionar Enter em um prompt de aprovação em branco não escolhe a opção recomendada. As abas Projeto e Conexão mostram um painel de detalhes do item selecionado para campos de backend, cobertura de relatório, estado de sincronização e registros vinculados; use J/K ou Seta para cima/baixo em Projetos e Conexões para mover a linha selecionada e depois Enter para confirmá-la. O cabeçalho de cobrança separa créditos restantes de créditos usados observados para que o uso não pareça o orçamento atual. Use o controle de Perfil ou /profile cost para executar o prompt atual com um Perfil de Agente; selecionar um perfil alterna a TUI para o modo Agente, e selecionar o modo Perguntar limpa o perfil de volta ao fluxo de chat padrão. Prompts iniciais permanecem ocultos até você executar /starter. Pressione Esc no prompt para sair da edição de texto para que tab, seta e atalhos numéricos se movam pelos controles e abas; digite novamente para retomar a edição. Carregadores ocupados e o cursor de entrada podem ser desativados com --no-anim. Os detalhes do banner incluem o usuário conectado. Controles focados e a aba superior ativa usam o acento amarelo de banner quente compartilhado, com a aba ativa preenchida em todo o seu interior de botão.

O CLI anuncia capacidades cloudeval.visualization/v1, flint-v1 e mermaid-v11 em solicitações de chat. O backend compila a intenção do gráfico; o CLI valida o artefato limitado e renderiza saída segura para terminal sem um navegador ou helper SVG nativo. Resultados JSON ask e agent incluem data.visualizations quando presentes, e NDJSON emite um evento visualization além de incluir os artefatos no result final. Respostas JSON/NDJSON finais, saída Markdown e histórico de conversa local retêm cercas de artefato validadas mesmo quando a prosa em streaming omite ou corrompe o payload do gráfico. A saída de texto permanece o fluxo de prosa ao vivo. Veja o contrato de artefato de visualização.

Fluxos de trabalho principais

Os ids de Perfil de Agente incluem architecture, cost, triage, remediation, visual-explainer, scripter, change-reviewer, evidence-auditor e security-reviewer. Os nomes de exibição podem conter espaços. O perfil Arquitetura inclui a lente de revisão Well-Architected, portanto não há um Perfil de Agente Well-Architected separado. Quando agents run omite um prompt, o CLI usa um prompt inicial para a fonte de projeto selecionada e o modo de perfil: modelo ou sincronização ao vivo, perguntar ou agente. A escolha é determinística para automação. Execuções de perfil enviam apenas agent_profile_id; o Cloudeval aplica instruções de perfil, lente de planejamento e padrões de resposta no backend. agents list e agents show primeiro tentam o catálogo de perfis do backend; se o endpoint do catálogo de perfis exigir login ou não estiver disponível, eles recorrem ao catálogo público incluído para que a descoberta ainda funcione. agents run ainda exige acesso autenticado ao backend. Na TUI, o seletor de Perfil usa os mesmos ids canônicos e envia o agent_profile_id selecionado com fluxos de chat.

Execute cloudeval <command> --help para flags exatas.

Chaves de acesso para CI e agentes

Use cloudeval login para humanos. A página de aprovação do navegador solicita um seletor de contas em todo login. Use chaves de acesso com escopo para CI, agentes hospedados e automação de longa duração.

Sessões de login por dispositivo armazenadas são atualizadas automaticamente antes de solicitações autenticadas. Se a TUI ou cloudeval ask receber uma resposta de token expirado do fluxo de chat, o CLI atualiza a sessão armazenada e tenta essa solicitação novamente uma vez. Se o token de atualização for revogado ou expirado, execute cloudeval login novamente. Crie uma chave de acesso após o login e a seleção do projeto:

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 exibe CLOUDEVAL_ACCESS_KEY e CLOUDEVAL_PROJECT_ID uma vez. A chave bruta não é mostrada novamente por credentials list ou credentials inspect.

Teste uma chave de acesso com escopo sem colocá-la no histórico do shell:

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

Regras de credenciais:

• prefira --access-key-stdin ou CLOUDEVAL_ACCESS_KEY;
• --access-key é aceito, mas gera um aviso porque argumentos de processo e histórico do shell podem vazar;
• nomes beta antigos --api-key, --api-key-stdin e CLOUDEVAL_API_KEY falham com um erro de migração;
• strings no formato de chave de acesso, cabeçalhos de autorização e parâmetros sensíveis de consulta em URLs são mascarados por padrão;
• arquivos de saída de criação de credenciais são gravados com permissões privadas em sistemas POSIX.

MCP Para Agentes de Codificação

Inicie o MCP após fazer login, ou forneça um CLOUDEVAL_ACCESS_KEY com escopo no ambiente do host:

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

Exemplos de configuração do cliente:

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

Regras do MCP:

• nomes de ferramentas usam sublinhados, como projects_list, recipes_list e billing_summary;
• nomes de ferramentas com pontos permanecem como aliases de compatibilidade;
• stdout é somente JSON-RPC e diagnósticos de [cloudeval-mcp] vão para stderr;
• esquemas de ferramentas MCP não aceitam argumentos de chave de acesso por chamada;
• mcp serve não suporta --access-key-stdin porque stdin é o fluxo do protocolo.
• readonly inclui ferramentas seguras de inspeção para projetos, relatórios, cobrança, conexões, credenciais, configuração, modelos, sessões, autenticação, status, doctor e receitas; geração, downloads, checkouts, mutação de credenciais, abertura de navegador e gravação de arquivos de diagrama permanecem explícitos.

Para inspeção de cobrança, use billing_ledger para tentativas de uso individuais e cobranças de crédito, billing_usage para agregados e billing_summary para direitos atuais. Os filtros do razão padrão são de 30 dias corridos; startAt e endAt substituem seus respectivos limites de intervalo. Passe data.next_cursor de volta como cursor com os mesmos filtros enquanto data.has_more for verdadeiro. O tamanho da página do razão padrão é 25 e é limitado a 1–100.

billing_invoices retorna faturas de assinatura, histórico de recargas pagas e status do ciclo de cobrança. Buscar esses dados pode criar registros de faturas de provedor ausentes para recargas já pagas e persistir links de recibos. Portanto, isso exige seleção explícita de --toolset billing ou --toolset all e é excluído de readonly. Seu limite de resultados padrão é 25, é limitado a 1–50 por coleção e não tem cursor de paginação. Essas ferramentas exigem acesso de leitura de cobrança por meio da credencial configurada do servidor; elas não iniciam uma compra nem alteram a assinatura.

Detalhes de configuração para desenvolvedores: cli.cloudeval.ai/developer/.

Receitas E Habilidades

As receitas do Cloudeval são fluxos de trabalho reutilizáveis para agentes e humanos. As receitas atuais cobrem revisão de custos, triagem de WAF, revisão de arquitetura, revisão de projetos de template, resumos de relatórios, planejamento de geração de relatórios, pacotes de exportação de relatórios, revisão de cobrança, prontidão para recarga, inventário de projetos e healthchecks, auditoria de conexões, configuração e rotação de credenciais, seleção de modelos, recuperação de sessões, verificações de onboarding da CLI, links de workspaces de frontend, exportações de diagramas de arquitetura/dependências e configuração do 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

Receitas baseadas em ask/agente podem consumir créditos de modelo. Receitas que criariam projetos, gravariam arquivos de relatório ou diagrama, alterariam a configuração do MCP, mutariam credenciais, abririam navegadores ou iniciariam fluxos de checkout exibem comandos explícitos em vez de realizar esses efeitos colaterais implicitamente. Instruções portáteis para agentes estão em skills/; o MCP continua sendo o caminho de execução preferido para Codex, Cursor, Claude e outros agentes.

Exemplo de Projeto

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

Use --template-url quando não quiser um arquivo local. Siga com reports run, reports download e projects export-diagram conforme necessário.

Saída, Autenticação E Privacidade

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

Contrato de saída:

• cloudeval login abre ou imprime uma URL de aprovação cloudeval.ai/device/login com uma dica de seletor de conta para o provedor de autenticação web;
• comandos legíveis por máquina gravam payloads em stdout;
• prompts, progresso, mensagens de abertura de navegador e avisos vão para stderr;
• ask e agent suportam --progress none, --quiet ou --format ndjson --progress ndjson;
• validate template e validate tests suportam --progress stderr ou --progress ndjson com --wait; o progresso da validação sempre vai para stderr para que o JSON/NDJSON final permaneça analisável em stdout. O progresso concluído inclui detalhes de verificações/testes com falha, como mensagem, recomendação, gravidade e localização do arquivo/template ou recurso quando disponível. Se um resultado de backend concluído tiver apenas um caminho de arquivo temporário local do worker, o Cloudeval relata o nome do template enviado;
• com --non-interactive, a aprovação humana sai com o código 6 e retorna HITL_REQUIRED;
• prompts interativos de HITL exigem um número de opção explícito, resposta do tipo sim/não ou resposta digitada; Enter em branco não aprova a opção recomendada;
• --show-sensitive-ids mostra IDs completos de conta/sessão apenas em máquinas confiáveis. Ele não desmascara tokens.

Documentação

Compilar a Partir do Código-Fonte

Leia AGENTS.md antes de tocar em autenticação, credenciais, artefatos de smoke ou comportamento de comandos voltados ao usuário.

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

Compile um binário autônomo para o sistema operacional atual:

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

Execute verificações:

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

Comunidade

• Aplicativo Cloudeval
• Documentação
• Versões
• Problemas
• Discord

Licença

A CLI do Cloudeval é um software proprietário fornecido sob a Licença da CLI do Cloudeval. A atribuição de pacotes de terceiros em produção é rastreada em THIRD_PARTY_NOTICES.md, com um SBOM de versão em sbom.spdx.json. As versões publicadas do instalador também baixam esses arquivos de aviso sob ~/.local/share/cloudeval/licenses. A política de versões está documentada em Conformidade de licença.