Documentation Index
Fetch the complete documentation index at: https://docs.cloudeval.ai/llms.txt
Use this file to discover all available pages before exploring further.
Use .cloudeval/config.yaml when a template-backed project has more than one file or when you want CloudEval to use a specific entry template.
Why it matters
CloudEval needs one explicit visualization source. In a repository with parameters, linked templates, modules, and generated outputs, the config file tells CloudEval which file starts the graph and report pipeline.
Quick example
Create this file at the root of your IaC workspace:
# .cloudeval/config.yaml
# CloudEval config v1.
# Only the documented keys below are read by CloudEval.
# Unknown keys and commented examples are ignored.
version: 1
stacks:
- id: main
entry: azuredeploy.json
parameters: azuredeploy.parameters.json
resolve:
linked_templates: true
analysis:
auto_resolve_on_import: false
auto_refresh_on_resolve: true
- CloudEval reads
azuredeploy.json as the visualization source.
- Relative
templateLink files are resolved when resolve.linked_templates is true.
- Generated bundles, connection mirrors, reports, and share assets are not treated as source files.
Supported keys
| Key | Required | Purpose |
|---|
version | Yes | Config schema version. Current supported value is 1. |
stacks[].id | Yes | Stable stack id used in status and generated bundle paths. |
stacks[].entry | Yes | Visualization source file, relative to the project root. |
stacks[].parameters | No | ARM parameters file, relative to the project root. |
resolve.linked_templates | No | Follows relative ARM templateLink files and merges them into the analysis bundle. Defaults to true. |
analysis.auto_resolve_on_import | No | Resolves the stack immediately after import. Defaults to false. |
analysis.auto_refresh_on_resolve | No | Refreshes diagram and reports after resolve. Defaults to true. |
Folder behavior
CloudEval treats the project root like a repository root. It does not add or strip a synthetic repo/ folder.
.cloudeval/
config.yaml
azuredeploy.json
nested/
network.json
README.md
repo, CloudEval treats it as a normal folder:
That means the config entry must include the folder:
stacks:
- id: main
entry: repo/azuredeploy.json
CLI and API contract
The public import contract is path based:
.cloudeval/config.yaml is read from the workspace root.stacks[].entry is the visualization source, relative to that same root.- Linked templates and parameters are uploaded as individual files and keep
their relative paths.
- CloudEval writes derived analysis artifacts under managed
.cloudeval/
subfolders; those artifacts are not source inputs.
The CLI follows the same contract when you use --workspace-dir:
cloudeval projects create \
--workspace-dir ./infra \
--workspace-entry azuredeploy.json \
--name "Nested ARM workspace" \
--provider azure \
--format json \
--output ./cloudeval-project.json
.cloudeval/config.yaml is missing, the CLI creates a minimal config using
the selected entry file and the detected parameters file, then sends that config
with the workspace upload. Passing --workspace-entry is recommended for
repositories with more than one deployable template.
Nested ARM example
Use this structure when a parent ARM template deploys child templates by
relative path:
.cloudeval/
config.yaml
azuredeploy.json
azuredeploy.parameters.json
nested/
network.json
storage.json
README.md
# .cloudeval/config.yaml
version: 1
stacks:
- id: main
entry: azuredeploy.json
parameters: azuredeploy.parameters.json
resolve:
linked_templates: true
analysis:
auto_resolve_on_import: true
auto_refresh_on_resolve: true
{
"resources": [
{
"type": "Microsoft.Resources/deployments",
"apiVersion": "2022-09-01",
"name": "network",
"properties": {
"mode": "Incremental",
"templateLink": {
"uri": "nested/network.json"
}
}
}
]
}
Ignored config and managed paths
CloudEval ignores unknown YAML keys so future fields can be added without breaking existing repositories. Comments are guidance only.
| Ignored item | Why |
|---|
| Unknown YAML keys | Forward-compatible; CloudEval v1 reads only the documented schema. |
| Commented examples | YAML comments are never parsed. |
.cloudeval/bundles/** | Derived resolved templates written by CloudEval. |
.cloudeval/connections/** | Derived connection mirrors written by CloudEval. |
.cloudeval/reports/** | User-visible report outputs written by CloudEval. |
.cloudeval/share/** and .cloudeval/shares/** | User-visible share assets and metadata written by CloudEval. |
.cloudeval/snapshots/** and .cloudeval/template-cache/** | Internal caches and snapshots written by CloudEval. |
.cloudeval/ps-rule.yaml | CloudEval-managed PSRule settings. This file is hidden from the normal project tree. |
Common mistakes
| Mistake | Fix |
|---|
Using .cloudeval/cloudeval.yaml | Rename it to .cloudeval/config.yaml. |
Setting entry to a generated bundle | Point entry at the source template, not .cloudeval/bundles/**. |
| Uploading generated report/share folders as source | Keep .cloudeval/reports/**, .cloudeval/share/**, and .cloudeval/shares/** as CloudEval-managed outputs. |
Expecting repo/ to be stripped | Use root-relative paths exactly as they exist in your repository. |
Related pages
