Cloudeval AI

Cloudeval CLI

Tu nube, en la terminal: evaluada, reportada y lista para agentes.

Cloudeval CLI convierte plantillas ARM, IaC alojado en GitHub y contexto vivo de Azure en señales de costo, arquitectura y Well-Architected. Úsalo como interfaz de terminal, cliente de automatización scriptable o servidor MCP para Codex, Cursor, Claude, VS Code y cualquier cliente stdio JSON-RPC.

Por Qué Usarlo

Instalar

Los usuarios de Node.js 20+ pueden instalar desde npm:

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

macOS, Linux, WSL2, Git Bash y PowerShell 7+ en Windows o Linux pueden usar el instalador de lanzamiento independiente:

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

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

Luego recarga tu shell e inicia sesión:

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

El inicio de sesión por dispositivo pasa por cloudeval.ai y siempre solicita al proveedor de autenticación del navegador que muestre el selector de cuentas, para que los usuarios puedan elegir el correo de trabajo previsto incluso cuando otra cuenta ya haya iniciado sesión. No se necesita ningún registro local de aplicación de Azure para el uso normal de la 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

Telemetría

Cloudeval CLI envía eventos personalizados seleccionados a Azure Application Insights por defecto. Los eventos cubren familia de comando, éxito, duración, enums de opciones seguras, versión de la CLI, versión de Node/runtime, versión principal del SO, arquitectura, fuente de instalación, resultados de actualización/instalación, nombres de herramientas MCP y metadatos de inicio/salida de la TUI. Después del inicio de sesión, los eventos pueden incluir el correo electrónico con sesión iniciada y el nombre/apellido/nombre completo.

La telemetría nunca envía prompts sin procesar, salida de comandos, tokens, rutas locales, identificadores de proyecto o recursos, identificadores de cuenta/sesión/tenant, nombres de recursos en la nube, trazas de pila o mensajes de error sin procesar. Desactívala o actívala de nuevo en cualquier 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

Las anulaciones de entorno tienen prioridad para una sola ejecución:

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

Actualiza más tarde con:

cloudeval update --check
cloudeval update --yes

Después de una actualización, reinicia o recarga los clientes MCP configurados cuando estés listo para cargar herramientas, recursos o prompts de Cloudeval recién expuestos. Cloudeval no reinicia Codex, Claude, Cursor, VS Code u otros hosts MCP automáticamente.

Desinstala los artefactos locales propiedad del instalador mientras conservas la configuración de Cloudeval, sesiones y autenticación por defecto:

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

Comienza Aquí

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

Documentación completa: Comienza con la CLI y Referencia de comandos de la CLI.

Dentro de la interfaz de terminal, usa el control de Hilo o /thread para cambiar entre sesiones de chat abiertas, hilos de chat recientes de Cloudeval y sesiones locales de la CLI. /thread new inicia otra sesión abierta independiente, y /open salta al mismo hilo de chat en Cloudeval cuando la sesión activa tiene un id de hilo. Las terminales espaciosas muestran un riel de contexto con chips de proyecto, hilo, modelo, modo, perfil, artefacto de informe; las terminales más estrechas mantienen el chat primero y exponen los mismos controles a través del compositor y comandos de barra. Escribir / abre una tira de completación de comandos en la parte inferior; usa Tab o Flechas Arriba/Abajo para moverte, Flecha Derecha para aceptar el texto fantasma y Enter para elegir el comando resaltado. El trabajo en streaming aparece como un registro de tareas en el hilo, y el compositor inferior permanece acoplado para que la entrada de prompts no compita con la transcripción. Las respuestas fundamentadas muestran citas numeradas y una sección de Fuentes en lugar de etiquetas [S_tool_...] sin procesar, con números de cita resaltados en línea; /copy copia la última respuesta del asistente y /download escribe una transcripción en Markdown con las mismas referencias. Los bloques de información de gráficos se renderizan como tarjetas de terminal con bordes en lugar de exponer marcadores graph-insight sin procesar; cuando una tarjeta contiene un diagrama de flujo Mermaid conservador, --graph-diagram auto renderiza un diagrama de terminal en TTY espaciosos, unicode o ascii fuerzan un modo, y off mantiene el respaldo de fuente Mermaid. La sintaxis Mermaid no compatible permanece visible como fuente en lugar de romper la transcripción. Las visualizaciones de chat negociadas se renderizan directamente en la TUI: las tendencias de línea/área usan gráficos Unicode; los datos de barras, columnas, histogramas, circulares, donas, radar y polares usan barras conscientes del ancho; los datos de dispersión y mapas de calor usan cuadrículas compactas de terminal; las familias de gráficos no compatibles usan el respaldo de tabla del artefacto. Los bordes de flujo Mermaid se renderizan como una lista de bordes, con fuente Mermaid limitada como respaldo cuando no se pueden extraer bordes. Los avisos de aprobación HITL requieren una selección de opción explícita o respuesta escrita; presionar Enter en un aviso de aprobación en blanco no elige la opción recomendada. Las pestañas de Proyecto y Conexión muestran un panel de detalles del elemento seleccionado para campos de backend, cobertura de informes, estado de sincronización y registros vinculados; usa J/K o Flechas Arriba/Abajo en Proyectos y Conexiones para mover la fila seleccionada, luego Enter para confirmarla. El encabezado de facturación separa los créditos restantes de los créditos usados observados para que el uso no parezca el presupuesto actual. Usa el control de Perfil o /profile cost para ejecutar el prompt actual con un Perfil de Agente; seleccionar un perfil cambia la TUI al modo Agente, y seleccionar el modo Preguntar limpia el perfil de vuelta al flujo de chat predeterminado. Los prompts iniciales permanecen ocultos hasta que ejecutes /starter. Presiona Esc desde el prompt para salir de la edición de texto para que los atajos de tab, flechas y números se muevan por controles y pestañas; escribe de nuevo para reanudar la edición. Los cargadores ocupados y el cursor de entrada se pueden desactivar con --no-anim. Los detalles del banner incluyen el usuario con sesión iniciada. Los controles enfocados y la pestaña superior activa usan el acento amarillo cálido compartido del banner, con la pestaña activa rellena en todo su interior de botón.

La CLI anuncia capacidades cloudeval.visualization/v1, flint-v1 y mermaid-v11 en solicitudes de chat. El backend compila la intención del gráfico; la CLI valida el artefacto limitado y renderiza salida segura para terminal sin navegador o helper SVG nativo. Los resultados JSON ask y agent incluyen data.visualizations cuando están presentes, y NDJSON emite un evento visualization además de incluir los artefactos en el result final. Las respuestas finales JSON/NDJSON, la salida Markdown y el historial de conversación local conservan vallas de artefactos validadas incluso cuando la prosa en streaming omite o corrompe el payload del gráfico. La salida de texto permanece como la transmisión de prosa en vivo. Consulta el contrato de artefactos de visualización.

Flujos de Trabajo Principales

Los ids de Perfil de Agente incluyen architecture, cost, triage, remediation, visual-explainer, scripter, change-reviewer, evidence-auditor y security-reviewer. Los nombres mostrados pueden contener espacios. El perfil de Arquitectura incluye la lente de revisión Well-Architected, por lo que no hay un Perfil de Agente Well-Architected separado. Cuando agents run omite un prompt, la CLI usa un prompt inicial para la fuente de proyecto seleccionada y el modo de perfil: plantilla o sincronización en vivo, preguntar o agente. La elección es determinista para automatización. Las ejecuciones de perfil envían solo agent_profile_id; Cloudeval aplica instrucciones de perfil, lente de planificación y valores predeterminados de respuesta en el backend. agents list y agents show primero intentan el catálogo de perfiles del backend; si el endpoint del catálogo de perfiles requiere inicio de sesión o no está disponible, recurren al catálogo público incluido para que el descubrimiento aún funcione. agents run aún requiere acceso autenticado al backend. En la TUI, el selector de Perfil usa los mismos ids canónicos y envía el agent_profile_id seleccionado con transmisiones de chat.

Ejecuta cloudeval <command> --help para banderas exactas.

Claves de Acceso Para CI Y Agentes

Usa cloudeval login para humanos. La página de aprobación del navegador solicita un selector de cuentas en cada inicio de sesión. Usa claves de acceso con ámbito para CI, agentes alojados y automatización de larga duración.

Las sesiones de inicio de sesión por dispositivo almacenadas se actualizan automáticamente antes de solicitudes autenticadas. Si la TUI o cloudeval ask recibe una respuesta de token expirado de la transmisión de chat, la CLI actualiza la sesión almacenada y reintenta esa solicitud una vez. Si el token de actualización está revocado o expirado, ejecuta cloudeval login de nuevo. Crea una clave de acceso después de iniciar sesión y seleccionar el proyecto:

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 imprime CLOUDEVAL_ACCESS_KEY y CLOUDEVAL_PROJECT_ID una vez. La clave sin procesar no se muestra nuevamente mediante credentials list ni credentials inspect.

Prueba una clave de acceso con ámbito sin ponerla en el historial del shell:

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

Reglas de credenciales:

• prefiere --access-key-stdin o CLOUDEVAL_ACCESS_KEY;
• --access-key se acepta pero advierte porque los argumentos del proceso y el historial del shell pueden filtrarse;
• los nombres beta antiguos --api-key, --api-key-stdin y CLOUDEVAL_API_KEY fallan con un error de migración;
• las cadenas con formato de clave de acceso, los encabezados de autorización y los parámetros sensibles de consulta en URL se redactan de forma predeterminada;
• los archivos de salida de creación de credenciales se escriben con permisos privados en sistemas POSIX.

MCP Para Agentes De Codificación

Inicia MCP después de iniciar sesión, o proporciona un CLOUDEVAL_ACCESS_KEY con ámbito en el entorno del host:

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

Ejemplos de configuración del 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

Reglas de MCP:

• los nombres de las herramientas usan guiones bajos como projects_list, recipes_list y billing_summary;
• los nombres de herramientas con puntos siguen siendo alias de compatibilidad;
• stdout es solo JSON-RPC y los diagnósticos de [cloudeval-mcp] van a stderr;
• los esquemas de herramientas MCP no aceptan argumentos de clave de acceso por llamada;
• mcp serve no admite --access-key-stdin porque stdin es el flujo del protocolo.
• readonly incluye herramientas de inspección seguras para proyectos, informes, facturación, conexiones, credenciales, configuración, modelos, sesiones, autenticación, estado, doctor y recetas; la generación, descargas, checkouts, mutación de credenciales, apertura de navegador y escritura de archivos de diagramas permanecen explícitas.

Para la inspección de facturación, usa billing_ledger para intentos de uso individuales y cargos de crédito, billing_usage para agregados y billing_summary para el derecho actual. Los filtros del libro mayor tienen como valor predeterminado 30 días calendario; startAt y endAt anulan sus límites de rango correspondientes. Pasa data.next_cursor de vuelta como cursor con los mismos filtros mientras data.has_more sea verdadero. El tamaño de página del libro mayor tiene como valor predeterminado 25 y se limita a 1–100.

billing_invoices devuelve facturas de suscripción, historial de recargas pagadas y estado del ciclo de facturación. Obtener estos datos puede crear registros de facturas de proveedor faltantes para recargas ya pagadas y persistir enlaces de recibos. Por lo tanto, requiere una selección explícita de --toolset billing o --toolset all y se excluye de readonly. Su límite de resultados tiene como valor predeterminado 25, se limita a 1–50 por colección y no tiene cursor de paginación. Estas herramientas requieren acceso de lectura de facturación a través de la credencial configurada del servidor; no inician una compra ni cambian la suscripción.

Detalles de configuración para desarrolladores: cli.cloudeval.ai/developer/.

Recetas Y Habilidades

Las recetas de Cloudeval son flujos de trabajo reutilizables para agentes y humanos. Las recetas actuales cubren revisión de costos, triaje de WAF, revisión de arquitectura, revisión de proyectos de plantilla, resúmenes de informes, planificación de generación de informes, paquetes de exportación de informes, revisión de facturación, preparación de recargas, inventario de proyectos y healthchecks, auditoría de conexiones, configuración y rotación de credenciales, selección de modelos, recuperación de sesiones, verificaciones de incorporación de CLI, enlaces de espacios de trabajo de frontend, exportaciones de diagramas de arquitectura/dependencias y configuración de 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

Las recetas respaldadas por ask/agente pueden consumir créditos de modelo. Las recetas que crearían proyectos, escribirían archivos de informes o diagramas, cambiarían la configuración de MCP, mutarían credenciales, abrirían navegadores o iniciarían flujos de checkout imprimen comandos explícitos en lugar de realizar esos efectos secundarios implícitamente. Las instrucciones portátiles para agentes se encuentran en skills/; MCP sigue siendo la ruta de ejecución preferida para Codex, Cursor, Claude y otros agentes.

Ejemplo De Proyecto

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

Usa --template-url cuando no quieras un archivo local. Continúa con reports run, reports download y projects export-diagram según sea necesario.

Salida, Autenticación Y Privacidad

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

Contrato de salida:

• cloudeval login abre o imprime una URL de aprobación de cloudeval.ai/device/login con una sugerencia de selector de cuenta para el proveedor de autenticación web;
• los comandos legibles por máquina escriben cargas útiles en stdout;
• los avisos, el progreso, los mensajes de apertura de navegador y las advertencias van a stderr;
• ask y agent admiten --progress none, --quiet o --format ndjson --progress ndjson;
• validate template y validate tests admiten --progress stderr o --progress ndjson con --wait; el progreso de validación siempre va a stderr para que el JSON/NDJSON final siga siendo analizable en stdout. El progreso completado incluye detalles de verificaciones/pruebas fallidas como mensaje, recomendación, gravedad y ubicación de archivo/plantilla o recurso cuando esté disponible. Si un resultado de backend completado solo tiene una ruta de archivo temporal local del trabajador, Cloudeval informa el nombre de la plantilla enviada en su lugar;
• con --non-interactive, la aprobación humana sale con el código 6 y devuelve HITL_REQUIRED;
• los avisos interactivos de HITL requieren un número de opción explícito, una respuesta de sí/no o una respuesta escrita; Enter en blanco no aprueba la opción recomendada;
• --show-sensitive-ids muestra IDs completos de cuenta/sesión solo en máquinas de confianza. No desredacta tokens.

Documentación

Compilar Desde El Código Fuente

Lee AGENTS.md antes de tocar autenticación, credenciales, artefactos de humo o comportamiento de comandos visibles para el usuario.

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

Compila un binario independiente para el sistema operativo actual:

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

Ejecuta verificaciones:

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

Comunidad

• Aplicación Cloudeval
• Documentación
• Lanzamientos
• Problemas
• Discord

Licencia

La CLI de Cloudeval es software propietario proporcionado bajo la Licencia de la CLI de Cloudeval. La atribución de paquetes de terceros en producción se rastrea en THIRD_PARTY_NOTICES.md, con un SBOM de lanzamiento en sbom.spdx.json. Los lanzamientos de instaladores publicados también descargan estos archivos de avisos bajo ~/.local/share/cloudeval/licenses. La política de lanzamiento está documentada en Cumplimiento de licencia.