# CloudEval AI llms-full.txt Last updated: 2026-05-17 Canonical product URL: https://cloudeval.ai Docs: https://docs.cloudeval.ai CLI overview: https://docs.cloudeval.ai/reference/cli-overview CLI command reference: https://docs.cloudeval.ai/reference/cli-command-reference CLI quickstart: https://docs.cloudeval.ai/quickstart/use-the-cli CLI automation workflow: https://docs.cloudeval.ai/workflows/automate-evaluations-with-the-cli Capabilities map: https://docs.cloudeval.ai/capabilities-map Evaluation coverage: https://docs.cloudeval.ai/reference/evaluation-coverage Short LLM context: https://cloudeval.ai/llms.txt CLI binaries: `cloudeval`, `eva` This is the detailed public LLM and agent reference for developers and agents using CloudEval AI. It describes app and CLI workflows, safe command usage, grounded outputs, permissions, and limitations. --- ## 1. What Is CloudEval AI CloudEval AI is a cloud intelligence platform for understanding cloud infrastructure through diagrams, evaluations, reports, and conversational workflows. CloudEval helps users: - Convert infrastructure into interactive diagrams. - Review cloud architecture, cost, security, and Well-Architected posture. - Chat with cloud/project context. - Generate reports and remediation-oriented insights. - Use the same project/report context from the web app or CLI. Core primitives: - Project: a CloudEval workspace for an infrastructure source. - Connection: the source used by a project, such as an uploaded template or cloud sync connection. - Diagram: an interactive view of resources and dependencies. - Report: a generated evaluation artifact, such as cost or Well-Architected output. - Chat thread: a grounded conversation over available project, diagram, connection, and report context. - Agent Profile: a product reviewer mode such as Architecture, Cost, Triage, or Remediation. Architecture includes the Well-Architected review lens. - CLI command: terminal workflow for automation and developer use. - Local hook: an opt-in local CLI automation event. --- ## 2. Why CloudEval Exists Cloud infrastructure work is often fragmented: - Diagrams drift from the actual infrastructure. - Cost, security, architecture, and compliance checks live in separate tools. - Cloud portals show resources but not always clear system relationships. - Reports are difficult to reproduce or share. - AI answers are unreliable when they are not grounded in project data. - Automation scripts often cannot reuse the same context as the UI. CloudEval reduces that fragmentation by giving users one place to inspect infrastructure, run evaluations, ask questions, and share findings. --- ## 3. Primary User Capabilities ### Infrastructure Import And Sync Current strong paths: - Upload or reference Azure ARM templates. - Use Bicep by compiling to ARM JSON or uploading generated ARM JSON. - Create template-backed projects from local files or remote template URLs. - Use Azure sync connections with service-principal credentials, subscription scope, and optional resource-group scope. Current web app project flow: - Open `Projects`, then choose `Create project`. - Add project details such as name, description, and provider. - Use `Template URL` for a GitHub-hosted template or `Upload Template File` for local JSON. - Add `Parameters file URL (optional)` or upload a parameters file when needed. - For GitHub template URLs, CloudEval can try to auto-detect a matching parameters file from the same repository. - Review the selected template source, then create the project and let CloudEval set up the backing connection in the background. Provider status: - Azure is the primary supported provider. - AWS and GCP may appear in some product contexts, but agents should not assume full live sync or full report parity unless current product capabilities confirm it. - Terraform, Pulumi, and CloudFormation should not be described as fully supported ingestion paths unless current capabilities confirm it. Canonical capability status: - Use https://docs.cloudeval.ai/capabilities-map for the human-readable current, in-progress, planned, and limited capability map. - Use https://docs.cloudeval.ai/feature-availability for the strict availability and limits matrix. - Use `cloudeval capabilities --format json` as the machine-readable CLI source of truth. ### Diagram Generation CloudEval can generate diagrams from imported or synced infrastructure context. User-facing diagram behavior: - Show cloud resources as nodes. - Show relationships/dependencies as edges. - Support architecture and dependency-style views. - Allow users to open a project directly to a diagram view. - Allow resource-focused links from CLI or app workflows. - Allow browser-based image downloads for PNG, JPEG, and SVG where available. - Allow native headless image downloads through `cloudeval projects export-diagram --layout architecture|dependency --format png|jpeg|svg --labels all|viewport --output `. Authenticated exports use the user's CloudEval login or a scoped automation credential; public/share exports require explicit public context. CLI output reports the resolved image path. ### Evaluations And Reports CloudEval report types include: - Cost reports. - Well-Architected / architecture reports. - Unit-test or template validation reports where available. - Evaluation coverage docs describe the public claim as 650+ cloud evaluation signals across Azure architecture checks, IaC deployment-readiness tests, graph intelligence, cost signals, and diagram integrity. - Report history and trends where report snapshots exist. - Issue and recommendation views derived from report data. Reports can include: - Summary metrics. - Resource-linked issues. - Recommendations. - Cost estimates and savings opportunities. - Well-Architected scores, pillars, and rules. - Exportable/shareable report views. Report audience behavior: - Executive views are concise and decision-focused. - Engineer views add resource identity, root cause, technical impact, remediation steps, evidence freshness, and validation detail in the main report surface. Report evidence behavior: - Confidence percentages are evidence-quality scores, not certainty claims. - Evidence drawers explain residual uncertainty from scan freshness, coverage gaps, rule specificity, pricing drift, and validation status. - Evidence drawers link live Azure ARM resources to the Azure portal when available, and also provide project preview and source report/code deeplinks for project-backed evidence. ### Chat And AI Interaction CloudEval supports chat over available project context. Useful questions: - "Summarize the top architecture risks." - "Which resources are most expensive?" - "What are the highest severity Well-Architected findings?" - "Which resources are public or risky?" - "What changed since the last report?" - "Create a short remediation plan from the report findings." Grounding expectations: - Answers should be based on project metadata, connection metadata, template content, diagram/resource graph data, saved reports, report history, pricing information, documentation sources, or chat history. - If required data is missing, the answer should say what is missing and suggest a concrete next step. --- ## 4. CLI Overview The CLI is for developers, platform engineers, automation scripts, and AI agents. Use the CLI when: - You prefer terminal workflows. - You want repeatable local setup and profiles. - You want diagnostics before using CloudEval in automation. - You need scriptable JSON output. - You want to run or fetch reports. - You want to inspect billing, credits, usage, or invoice metadata. - You want to ask one grounded question without opening the UI. - You want to expose CloudEval to an MCP-compatible agent tool. - You want to open a precise app deeplink. - You are building an automation or agent workflow. Use the web app when: - You need visual diagram inspection. - You need interactive report exploration. - You need project setup flows not exposed in CLI. - You need collaboration, UI review, or export workflows. --- ## 5. CLI Installation And Auth Canonical CLI docs: - CLI overview: https://docs.cloudeval.ai/reference/cli-overview - CLI command reference: https://docs.cloudeval.ai/reference/cli-command-reference - Use the CLI: https://docs.cloudeval.ai/quickstart/use-the-cli - Automate evaluations with the CLI: https://docs.cloudeval.ai/workflows/automate-evaluations-with-the-cli - Agent and LLM context guide: https://docs.cloudeval.ai/reference/llms-and-agent-context Install with npm on Node.js 20+: ```bash npm install -g @ganakailabs/cloudeval-cli ``` Or install the standalone release binary: ```bash curl -fsSL https://cli.cloudeval.ai/install.sh | bash ``` The standalone installer detects Codex, Cursor, Claude, and VS Code when their CLIs are available, then optionally offers login, access-key guidance, and MCP setup. CI and non-interactive installs print next steps rather than prompting. Verify: ```bash cloudeval --version eva --version ``` Configure a local profile: ```bash cloudeval setup --non-interactive --profile quickstart --model gpt-5-nano --format json cloudeval config show --profile quickstart --format json cloudeval status --profile quickstart --format json cloudeval doctor --profile quickstart --format json ``` Login: ```bash cloudeval login ``` Headless login: ```bash cloudeval login --headless cloudeval login --headless --verbose ``` Headless login uses CloudEval's device-code approval flow. The web approval URL includes an account-chooser prompt so existing browser sessions do not silently approve the wrong identity. In a custom deployment, make sure the same CloudEval web origin exposes that approval path. Check auth: ```bash cloudeval auth status ``` Logout: ```bash cloudeval logout cloudeval logout --all-devices ``` Automation safety: - Use `cloudeval login --headless` for SSH, containers, or remote terminals. - Use scoped access keys for CI or agent automation instead of browser login. - Prefer `--non-interactive` in CI or agent contexts. - Prefer `--format json` for scripts. - Prefer `--profile ` when multiple agents or environments share one host. - Prefer `--print-url --no-open` when a command can generate a web URL. --- ## 6. Current CLI Command Surface Use this as a guide, but treat `cloudeval capabilities --format json` as the command source of truth. ### Top-Level / UI ```bash cloudeval cloudeval tui cloudeval tui --tab reports --project ``` Purpose: - Opens the terminal UI. - Supports tabs such as chat, overview, reports, projects, connections, billing, options, and help. ### Setup And Config ```bash cloudeval setup --non-interactive --profile quickstart --model gpt-5-nano --format json cloudeval config show --profile quickstart --format json cloudeval config get model --profile quickstart cloudeval config set model gpt-5-nano --profile quickstart --format json cloudeval config profiles --format json ``` Purpose: - Store local defaults for service URL, web app URL, default project, model, and output preferences. - Keep separate environments or agents isolated with named profiles. ### Auth ```bash cloudeval login cloudeval login --headless cloudeval auth status cloudeval logout cloudeval logout --all-devices ``` Purpose: - Authenticate, inspect auth state, and clear local/session auth. ### Credentials And Access Keys ```bash cloudeval credentials templates --format json cloudeval credentials create --template ci --name github-actions-prod --project --expires 90d --format github-actions cloudeval credentials list --project --format json cloudeval credentials inspect --format json cloudeval credentials revoke --reason "rotated" --format json cloudeval identity --format json cloudeval capabilities --live --format json ``` Purpose: - Create scoped access-key credentials for CI/CD, MCP, and agent automation. - Inspect the current CloudEval identity, effective capabilities, limits, and credential templates. - Use `CLOUDEVAL_ACCESS_KEY` or `--access-key` for automation credentials. - The Developer area supports project-scoped access keys, CLI setup, MCP setup, Agent Profiles, and agent workflow guidance. - Access keys are scoped for automation and must not be treated as user passwords. ### Diagnostics ```bash cloudeval status --profile quickstart --format json cloudeval doctor --profile quickstart --format json cloudeval doctor --profile quickstart --deep --format json cloudeval doctor --mcp --format json ``` Purpose: - Inspect current profile, config, auth, service URL, and Node.js status. - Check local CLI health before automation. - Use `doctor --deep` for a best-effort CloudEval service reachability check in addition to local checks. - Use `doctor --mcp` before registering CloudEval with an MCP-compatible client. ### Chat Assistant stream `summary` events may include citation metadata: `citation_markers` (claim spans + `source_index`), `citations` (`title`, `url`, `quote`, `loc`, `alignment_score`, `origin`), and `citation_alignment_stats`. Web and CLI render inline `[n]` pills from `[S…]` tags; press `1`–`9` in CLI chat to inspect a source. ```bash cloudeval chat --project cloudeval chat --continue cloudeval chat --resume cloudeval ask "Summarize project risk" --project --format json --non-interactive cloudeval agent "Run a cost review and tell me the next action" --project --format markdown --non-interactive cloudeval ask "Follow up on the same investigation" --thread --format json --non-interactive cloudeval agents list --format json cloudeval agents show cost --format json cloudeval agents run architecture --project --format json ``` Purpose: - `chat`: interactive terminal chat. - `chat --continue` resumes the latest local session. - `chat --resume` resumes a session by ID or title. - `ask`: one-shot non-interactive question, best for automation. - `agent`: one-shot agent-mode task execution with progress on stderr and final output on stdout. - `agents list|show|run`: product Agent Profiles for named reviewer workflows. - `ask --thread` appends a one-shot follow-up to an existing local session. - Public Agent Profile ids and names are single-word labels: Architecture, Cost, Triage, and Remediation. Architecture includes the Well-Architected review lens. - Use `agents run ` when the workflow should use a named product reviewer. Keep `agent ""` for freeform agent mode. - Use General (built-in chat) when no named reviewer profile is needed. ### Local CLI Hooks ```bash cloudeval agents run cost --project --format json cloudeval agents run cost --project --no-hooks ``` Purpose: - Run explicit opt-in local shell hooks around selected CLI command and Agent Profile events. - Hook configuration lives in the local CLI profile config under `hooks.enabled` and `hooks.events`. - Supported events are `cli.command.before`, `cli.command.after`, `cli.command.error`, `agent_profile.run.before`, `agent_profile.run.after`, and `agent_profile.run.error`. - Hooks receive context through environment variables and a temporary JSON payload file. - Before-hook failure aborts unless the hook sets `continueOnError`; after/error hook failures are warnings. - Hooks are local-only. They are not hosted automation rules, hosted automation state, or outbound webhooks. ### Models And Sessions ```bash cloudeval models list --profile quickstart --format json cloudeval models default set gpt-5-nano --profile quickstart --format json cloudeval sessions list --profile quickstart --format json cloudeval sessions get --profile quickstart --format json cloudeval sessions search "cost spike" --profile quickstart --format json cloudeval sessions rename "Production cost review" --profile quickstart --format json cloudeval sessions export --profile quickstart --format json ``` Purpose: - Inspect available models and set a profile default. - Review, search, rename, export, or clean up local session history produced by CLI chat and one-shot runs. ### Skills And Recipes ```bash cloudeval recipes list cloudeval recipes show cost-review --format markdown cloudeval recipes run cost-review --project --format markdown --non-interactive cloudeval recipes run waf-triage --project --format json --non-interactive ``` Purpose: - Discover public CloudEval skill-guided workflows for agents and users. - Run repeatable workflows layered on existing CLI and MCP capabilities. - Current recipes include `cost-review`, `waf-triage`, `architecture-review`, `template-project-review`, `report-summary`, `billing-review`, `diagram-export`, and `mcp-setup`. - Skills cover agent operations, projects/diagrams, reports, cost, architecture, billing, credentials, connections, and MCP diagnostics. ### Projects ```bash cloudeval projects list --format json cloudeval projects get --format json cloudeval projects open --view preview --layout architecture cloudeval projects export-diagram --layout architecture --format png --labels all --output architecture.png --non-interactive cloudeval projects create --template-file ./azuredeploy.json --name "First import" --provider azure --profile quickstart --format json cloudeval projects create --template-url https://github.com/Azure/azure-quickstart-templates/blob/master/quickstarts/microsoft.compute/1vm-2nics-2subnets-1vnet/azuredeploy.json --name "First import" --provider azure --profile quickstart --format json ``` Browser-only GitHub repository import: - Install the CloudEval GitHub App on selected repositories. - Create an Infrastructure as code project from repository, branch, and optional source root. - CloudEval imports root-relative files, reads `.cloudeval/config.yaml`, resolves linked ARM templates, and keeps source files read-only while synced from GitHub. - Push webhooks and the project-page **Sync from GitHub** action refresh the imported workspace, diagram, and reports. Purpose: - List, inspect, open, create, or download diagram images for CloudEval projects. - Create supports template file/URL workflows; browser project creation also supports GitHub repository import through the GitHub App. Common create options: - `--template-file ` - `--template-url ` - `--parameters-file ` - `--parameters-url ` - `--name ` - `--description ` - `--provider azure|aws|gcp` ### Connections ```bash cloudeval connections list --format json cloudeval connections get --format json cloudeval connections open ``` Purpose: - Inspect CloudEval connections and open connection pages. ### MCP Server ```bash cloudeval mcp status --format json cloudeval doctor --mcp --format json cloudeval mcp setup codex --dry-run cloudeval mcp setup claude --dry-run --toolset reports --format json cloudeval mcp setup cursor --dry-run --toolset billing --format json cloudeval mcp setup vscode --dry-run --toolset readonly cloudeval mcp setup generic --dry-run --toolset readonly --format json cloudeval mcp serve cloudeval mcp serve --toolset readonly codex mcp add cloudeval -- cloudeval mcp serve ``` Purpose: - Run CloudEval as a local stdio MCP server for agent tools that support the Model Context Protocol. - Expose CloudEval tools such as `ask`, `projects.list`, `projects.get`, `projects.exportDiagram`, `reports.list`, `reports.run`, `reports.download`, `billing.summary`, `billing.usage`, `billing.ledger`, `agentProfiles.list`, `agentProfiles.get`, `agentProfiles.run`, `open.url`, and `capabilities.get`. - Generate setup instructions for Codex, Claude Desktop, Cursor, VS Code, and generic JSON-configured MCP clients. - Use `generic` when a client accepts an `mcpServers` JSON entry. For Ollama-powered agents, configure the MCP-capable agent host launched by Ollama with the generated CloudEval stdio entry. Focused toolsets: - `all`: full CloudEval MCP surface. - `readonly`: read-only project, report, billing, Agent Profile, and capability discovery. - `projects`: project lookup and project deeplinks. - `reports`: project lookup, report runs, report downloads, and report deeplinks. - `billing`: billing summaries, usage, ledger entries, and billing deeplinks. MCP resources: - `cloudeval://capabilities` - `cloudeval://projects` - `cloudeval://billing/summary` - `cloudeval://reports/latest` - `cloudeval://recipes` MCP prompts: - `cost-review` - `waf-triage` - `architecture-review` - `billing-review` - recipe prompts exposed by the recipe catalog when the active toolset allows them Notes: - Use stored `cloudeval login` auth, `cloudeval login --headless`, or a scoped `CLOUDEVAL_ACCESS_KEY`. - `mcp serve` uses stdin for MCP JSON-RPC messages and cannot run an interactive login prompt. - `--verbose` writes diagnostics to stderr. ### Reports ```bash cloudeval reports list --project --kind all --format json cloudeval reports run --project --type all --wait --format json cloudeval reports cost --project --format markdown cloudeval reports waf --project --format markdown cloudeval reports rules --project --format json cloudeval reports show --project --format json cloudeval reports download --project --type all --output ./reports ``` Purpose: - List, generate, inspect, and download report data. Report run types: - `cost` - `waf` - `architecture` - `unit-tests` - `all` Download types: - `cost` - `waf` - `architecture` - `all` Download behavior: - `--type all` currently downloads the available cost and WAF/architecture payloads. - `--type architecture` maps to the WAF/architecture report payload. Payload views: - `raw` - `parsed` - `formatted` ### Open Deeplinks ```bash cloudeval open overview --print-url --no-open cloudeval open chat --thread --print-url --no-open cloudeval open project --view both --layout dependency --print-url --no-open cloudeval open reports --project --tab overview --print-url --no-open cloudeval open reports --project --download-pdf --pdf-verbosity detailed --print-url --no-open cloudeval open billing --tab usage --print-url --no-open ``` Purpose: - Print or open authenticated CloudEval web app URLs. ### Billing And Credits ```bash cloudeval credits --format json cloudeval billing summary --format json cloudeval billing plans --format json cloudeval billing usage --range 30d --format json cloudeval billing ledger --limit 25 --format json cloudeval billing invoices --limit 25 --format json cloudeval billing topups --limit 25 --format json cloudeval billing notifications --limit 25 --format json ``` Purpose: - Inspect credit status, subscription/billing summary, plan metadata, usage summaries, usage ledger entries, invoices, top-up packs, and billing notifications. - These commands read CloudEval account/billing metadata; they do not create payments or mutate cloud infrastructure. ### Capability Discovery ```bash cloudeval capabilities --format json cloudeval help agents cloudeval completion zsh ``` Purpose: - Discover supported commands/options for agents. - Generate shell completion. --- ## 7. Commands Not To Assume Do not call these as top-level commands unless `cloudeval capabilities --format json` confirms they exist: - `cloudeval init` - `cloudeval connect` - `cloudeval sync` - `cloudeval evaluate` - `cloudeval diagram` - `cloudeval report` Current mappings: - Init: `cloudeval setup`, then `cloudeval login` and `cloudeval auth status`. - Connect/import: `cloudeval projects create --template-file ...` or `cloudeval projects create --template-url ...`. - Sync/status: `cloudeval status`, `cloudeval doctor`, `cloudeval connections get ...`, or app sync flows where available. - Evaluate: `cloudeval reports run ...`. - Diagram: `cloudeval open project ... --view preview --layout architecture|dependency`. - Report: `cloudeval reports ...`. - Headless diagram image download: use `cloudeval projects export-diagram --layout architecture|dependency --format png|jpeg|svg --labels all|viewport --output ` for authenticated downloads after `cloudeval login`, `cloudeval login --headless`, or a scoped automation credential. Use `--public` only for explicit public/share graph data. `--labels all` is the default and forces resource names plus edge labels; `--labels viewport` preserves normal progressive label visibility. --- ## 8. Example Workflows ### Create A Project In The Web App From A GitHub URL 1. Open `Projects`. 2. Choose `Create project`. 3. In `Project Details`, enter a name and choose `Azure`. 4. Paste a real template URL into `Template URL`, for example: ```text https://github.com/Azure/azure-quickstart-templates/blob/master/quickstarts/microsoft.compute/1vm-2nics-2subnets-1vnet/azuredeploy.json ``` 5. Watch the optional parameters area report `Looking...`, then `Found` or `Not found`. 6. Review the selected `Template Source`, then create the project. Expected outcome: - CloudEval creates the project. - A backing connection is created from the template URL. - The project can open into the workspace after processing begins. ### Create A Project In The Web App From Local ARM JSON 1. Open `Projects`. 2. Choose `Create project`. 3. In `Project Details`, enter a name and choose `Azure`. 4. Use `Upload Template File` for files such as `./azuredeploy.json`. 5. Add a parameters file if needed, such as `./azuredeploy.parameters.json`. 6. Review the selected `Template Source`, then create the project. Expected outcome: - CloudEval creates the project from the uploaded JSON. - The imported files become part of the project workspace. - Reports and follow-up review happen inside the same project. ### Import ARM JSON And Open Diagram ```bash cloudeval setup --non-interactive --profile quickstart --model gpt-5-nano --format json cloudeval login cloudeval projects create \ --template-file ./azuredeploy.json \ --name "Production import" \ --provider azure \ --profile quickstart \ --format json cloudeval open project --view preview --layout architecture ``` Expected outcome: - A CloudEval project is created. - The project can be opened in the web app. - The diagram is available after project processing/sync completes. ### Compile Bicep Then Import ```bash az bicep build --file main.bicep cloudeval projects create \ --template-file ./main.json \ --name "Main Bicep import" \ --provider azure \ --profile quickstart \ --format json ``` Expected outcome: - Bicep is converted to ARM JSON first. - CloudEval imports the ARM JSON. ### Run Full Evaluation ```bash cloudeval reports run --project --type all --wait --format json cloudeval reports cost --project --format markdown cloudeval reports waf --project --format markdown ``` Expected outcome: - Report generation is submitted. - Cost and Well-Architected outputs can be inspected. ### Ask A Grounded Question ```bash cloudeval ask \ "What are the top 5 risks in this project and what should I fix first?" \ --project \ --profile quickstart \ --format json \ --non-interactive ``` Expected outcome: - The answer uses available project/report/context data. - If reports are missing, the answer should identify that gap. ### Download Report Data For Automation ```bash cloudeval reports download \ --project \ --type all \ --view formatted \ --output ./reports ``` Expected outcome: - Report files are written locally. - Automation can process the files. ### Generate A Shareable App URL ```bash cloudeval open reports \ --project \ --tab overview \ --download-pdf \ --pdf-verbosity evidence \ --print-url \ --no-open ``` Expected outcome: - A URL is printed to stdout. - The browser is not opened. - For report file exports, use the app download controls or the CLI report export commands. - For project diagram image exports, use the app diagram download controls when working in the browser. - For CLI and MCP agents that need the bytes directly, prefer `cloudeval projects export-diagram` or the MCP `projects.exportDiagram` tool instead of scraping project pages. --- ## 9. Agent And Automation Rules Agents should: - Fetch `/llms.txt` first. - Fetch `/llms-full.txt` when detailed CLI/workflow context is needed. - Run `cloudeval capabilities --format json` before relying on command names. - Run `cloudeval doctor --format json` before relying on a local install. - Prefer JSON output. - Use `--non-interactive` in automation. - Use `--profile ` when multiple agents or environments share one host. - Use `--print-url --no-open` for deeplink generation. - Use `cloudeval mcp serve` when the agent framework already supports MCP. - Use `cloudeval recipes list` before inventing a repeatable CloudEval workflow. - Use `cloudeval mcp setup generic --dry-run --toolset readonly --format json` for MCP clients that accept `mcpServers` JSON, including Ollama-powered agent hosts. - Use project IDs, report IDs, connection IDs, and thread IDs from actual command output. - Avoid parsing terminal UI output. - Avoid claiming support for commands or providers not confirmed by current capabilities. Stable automation pattern: ```bash cloudeval capabilities --format json cloudeval doctor --profile quickstart --format json cloudeval projects list --format json --non-interactive cloudeval reports list --project --kind all --format json --non-interactive cloudeval ask "Summarize current project posture" --project --format json --non-interactive ``` --- ## 10. ASK Mode Vs AGENT Mode ASK mode: - Read-first. - Best for answers, summaries, explanations, and report interpretation. - Should not silently perform actions. - Should state missing evidence when data is unavailable. AGENT mode: - Multi-step. - Can use more tools. - Can run guarded CloudEval artifact actions when explicitly requested. - Should distinguish read operations from actions that create or regenerate CloudEval artifacts. Examples of guarded actions: - Create a CloudEval project. - Create a template-backed CloudEval connection. - Run a cost report. - Run a Well-Architected/architecture report. - Run unit-test/report validation. - Save generated report artifacts. Agents should not claim CloudEval changes customer cloud resources unless a verified capability explicitly supports that behavior. --- ## 11. Data And Trust Model CloudEval outputs are useful when they are grounded in available user/project data. Typical evidence sources: - Project metadata. - Connection metadata. - Uploaded or referenced ARM/Bicep-derived template content. - Diagram/resource relationship data. - Cost reports. - Well-Architected/architecture reports. - Unit-test/template validation reports. - Report history and trends. - Pricing data. - Cloud documentation or Well-Architected reference docs. - Chat thread history. Trust expectations: - Do not invent resources, costs, risks, or cloud accounts. - If a report is missing, stale, or incomplete, say so. - If cloud coverage is limited, say so. - If a result is an estimate, call it an estimate. - Treat report confidence as a calibrated evidence-quality score; do not phrase it as absolute proof. - If a workflow requires the web UI, say that CLI coverage is limited. --- ## 12. Security And Permissions Security model for tool users: - Authentication is required for user projects and reports. - CLI auth should use the normal `cloudeval login` flow unless automation credentials are intentionally provided. - Service-principal style cloud connections should be scoped with least privilege. - Read-oriented access is the expected model for cloud discovery and evaluation. - CloudEval report/chat workflows should not be described as mutating customer cloud resources by default. - Secrets should not be pasted into prompts, reports, or command history. CLI safety: - Use `--non-interactive` for scripts and CI. - Use stored login state, headless login state, or a scoped access key for `cloudeval mcp serve`. - Use focused MCP toolsets when an assistant only needs read-only, project, report, or billing access. - Avoid logging tokens or secrets. - Treat shared URLs as authenticated app deeplinks unless explicitly public. --- ## 13. Roadmap Direction The public roadmap is a six-month, evidence-first plan for making CloudEval a trusted cloud diagnostic workspace. The docs capabilities map at https://docs.cloudeval.ai/capabilities-map is the stable reference for current, in-progress, planned, and limited capabilities. The roadmap should be read as product direction, not as a promise that every planned item is already available. Roadmap status labels: - `Shipped`: already implemented current capability. - `Active now`: currently being hardened or expanded. - `Next`: the nearest upcoming milestone. - `Planned`: intended roadmap work that should not be described as shipped. - `Beta track`: preview/beta/research work that needs explicit coverage labels. Roadmap milestones: - Available today / May 2026: already implemented app, CLI, MCP server, interactive architecture and dependency diagrams, Azure ARM/Bicep imports, Azure live sync, Well-Architected/cost/security/architecture reports, ARM/unit-test reports where available, grounded chat, diagnostics, exports, and authenticated deeplinks. - June 2026: fix IaC risks inside VS Code. Planned editor sidebar for projects/resources/findings, inline ARM/Bicep diagnostics, CodeLens actions, and MCP tools so VS Code agents can ask grounded cloud questions. - July 2026: preview cloud changes before merge. Planned repository IaC scanning, pull request diagram diffs, GitHub Checks annotations, and CI gates for critical architecture, security, reliability, drift, and spend regressions. - August 2026: investigate drift and blast radius. Planned snapshot history, drift detection, graph diff, dependency tracing, exposure-path exploration, and operational questions such as what changed, why cost moved, and what can reach a resource. - September 2026: evaluate multi-cloud without hiding gaps. Beta-track AWS sync, GCP asset discovery, Terraform/CloudFormation ingestion, Kubernetes cost, and telemetry evidence with explicit parser, provider, rule, and data coverage labels. Do not assume parity with Azure unless current capabilities confirm it. - October 2026: turn findings into PR-ready fixes. Planned ranked remediation, safe IaC patch generation, GitHub pull requests, waivers, owners, reasons, expiry dates, audit trails, and evidence exports. Agent guidance: - Treat roadmap items as future direction unless they are explicitly marked as shipped or appear in current capabilities. - When users ask about VS Code, GitHub PR checks, AWS/GCP sync parity, Terraform, CloudFormation, Kubernetes, telemetry, or automated remediation, state the roadmap status and avoid claiming those workflows are generally available. - Prefer evidence-first wording: resource, rule/source, confidence, freshness, coverage, and remediation. --- ## 14. Limitations - Azure is the primary supported provider. - ARM JSON is the strongest current IaC path. - Bicep should be compiled to ARM JSON for CLI upload. - Full AWS/GCP live sync parity should not be assumed. - Terraform/Pulumi/CloudFormation support should not be assumed unless current capabilities confirm it. - Diagram freshness depends on project/connection processing or sync status. - Report quality depends on available project/template/cloud/report data. - Cost values are estimates unless connected to authoritative billing data for the relevant scope. - Security and architecture findings are recommendations/evaluations, not compliance attestation. - Some setup or visual review workflows may require the web UI. - Roadmap items are not shipped behavior unless marked as shipped or listed under current capabilities. --- ## 15. Public URLs - `/llms.txt`: short agent entrypoint. - `/llms-full.txt`: detailed developer and agent context. - `/llm.txt`: redirects to `/llms.txt`. - `/llm-full.txt`: redirects to `/llms-full.txt`. - `/search-index.json`: app search index. - `/sitemap.xml`: sitemap. - `/robots.txt`: crawler and agent discovery hints. - `/home`: public homepage. - `/home/roadmap`: public roadmap. - `/app/overview`: authenticated overview. - `/app/chat`: authenticated chat. - `/app/projects`: authenticated projects. - `/app/connections`: authenticated connections. - `/app/reports`: authenticated reports. - `/app/subscription`: authenticated subscription/billing. --- ## 15.1 Phase 1 public AEO pages These pages are public, indexable, and conservative around shipped CloudEval capability. They should be treated as Azure-first answer pages for diagrams, source-linked architecture Q&A, CLI workflows, MCP-compatible agents, templates, and comparisons. - `/answers/how-to-generate-azure-architecture-diagram`: how to generate Azure architecture diagrams from ARM/Bicep context or live Azure sync. - `/answers/arm-template-to-architecture-diagram`: how to convert Azure ARM templates into CloudEval diagrams and report-backed reviews. - `/answers/bicep-to-cloud-diagram`: how to use compiled Bicep ARM JSON with CloudEval. - `/answers/chat-with-azure-architecture`: how to ask CloudEval AI grounded questions about Azure architecture. - `/answers/ai-cloud-architecture-assistant`: what CloudEval's grounded AI architecture assistant can do. - `/answers/mcp-server-for-cloud-architecture`: how CloudEval MCP workflows help compatible agents query project, graph, report, pricing, documentation, and chat context. - `/answers/cloud-architecture-cli`: what the CloudEval CLI can do for architecture review workflows. - `/answers/export-cloud-diagrams-from-cli`: how to export architecture and dependency diagrams from the CLI. - `/templates/azure-hub-spoke-network`: Azure hub-spoke network template with architecture explanation and evidence notes. - `/compare/lucidscale-alternative`: CloudEval versus Lucidscale for Azure review, AI Q&A, CLI, MCP, reports, exports, and multi-cloud visualization fit. - `/compare/cloudcraft-alternative`: CloudEval versus Cloudcraft for Azure review, AWS-first diagramming fit, visual design, AI Q&A, CLI, MCP, exports, and cost context. - `/compare/hava-io-alternative`: CloudEval versus Hava.io for Azure review, multi-cloud diagram monitoring, history, diff, AI Q&A, CLI, MCP, and exports. - `/compare/cloudockit-alternative`: CloudEval versus Cloudockit for Azure review, documentation packages, office-format outputs, AI Q&A, CLI, MCP, and exports. - `/compare/drawio-cloud-diagram-alternative`: CloudEval versus draw.io for generated Azure review diagrams compared with manual cloud diagram editing. - `/compare/lucidchart-cloud-diagram-alternative`: CloudEval versus Lucidchart for Azure review, project-aware AI, CLI, MCP, templates, and visual collaboration. Do not use these pages to imply full AWS, GCP, Terraform, Pulumi, or CloudFormation parity. Azure ARM/Bicep and Azure live sync remain the primary shipped ingestion story unless current capabilities confirm otherwise. --- ## 16. Freshness And Verification Use this file as stable grounding, then verify runtime behavior before automation. - Treat `Last updated` as a freshness hint, not a guarantee. - Before CLI automation, run `cloudeval capabilities --format json`. - Prefer current CLI capability output over command examples in this file when they conflict. - Prefer current app behavior over stale route or workflow descriptions. - If a workflow requires unavailable data, ask for the missing project, connection, report, or cloud scope. - If provider or IaC support is ambiguous, state the uncertainty and avoid assuming parity.