CLI command reference

This page documents the current shipped command surface. Before you bake any command into automation, run:

cloudeval capabilities --format json

That command is the most reliable source of truth for machine consumers. Most pipeable commands also support --profile <name>. Profiles let you keep separate CloudEval service URLs, app URLs, default projects, and model defaults for different agents, environments, or workspaces.

Structured command help

Use these shapes when you are wiring Cloudeval into scripts, CI, or agent tools. The command tables below remain the full index; this section documents the commands whose inputs and JSON output are most often parsed by automation. Required fields are based on the current CLI implementation in cloudeval-cli.

Create an Infrastructure as code project

cloudeval projects create \
  --workspace-dir ./infra \
  --workspace-entry azuredeploy.json \
  --name "Nested ARM workspace" \
  --provider azure \
  --format json \
  --output ./cloudeval-project.json

string | boolean

required

Use one project source for a source-backed create: --template-file, --template-url, --workspace-dir, or --cloud-sync. The CLI rejects commands that combine multiple source modes.

string

Local directory containing ARM JSON, parameter files, nested templates, and optional .cloudeval/config.yaml.

string

Entry template relative to --workspace-dir. Use this when the workspace has more than one deployable template.

string

Parameters file relative to --workspace-dir.

string

Single local ARM JSON template. Use this instead of --workspace-dir for a one-file import.

string

Raw or GitHub template URL for a one-time import from a public source.

string

Optional parameter source. The CLI allows these only with --template-file or --template-url.

boolean

Creates a live Azure inventory project from scoped Azure credentials instead of importing a static template.

string

required

Required when --cloud-sync is used.

string

required

Required when --cloud-sync is used.

string

required

Required when --cloud-sync is used. Prefer the environment variable or stdin form so the secret is not stored in shell history.

string

required

Required when --cloud-sync is used.

string | array

Optional Azure resource group scope for Cloud sync.

string

Project name shown in the Cloudeval app, reports, and follow-up command output. If omitted, the CLI infers a name from the workspace, source, or Cloud sync mode where possible.

string

Cloud provider. Defaults to azure; --cloud-sync currently supports Azure only.

object

required

Created project record. data.project.id is the value to pass to --project on review, report, graph, and ask commands.

object

Created or linked connection record when the source creates a reusable connection.

object

Cloud sync status returned when project creation starts a sync workflow.

object

Inferred source metadata such as detected parameters or source shape when available.

object

IaC import, resolve, and analysis pipeline state when a workspace or template source starts that flow.

Review a pull request or pushed commit

cloudeval review \
  --project "$PROJECT_ID" \
  --format json \
  --non-interactive

string

required

Provide --project, or run inside a GitHub-backed repository that maps to exactly one Cloudeval project. Without one of those contexts, the CLI cannot choose what to review.

string

Cloudeval project id linked to the repository being reviewed.

string

Optional owner/repo override. By default, the CLI reads the current Git remote.

string

Git ref to review. By default, the CLI uses the current branch.

string

Commit SHA to sync and review. By default, the CLI uses HEAD.

string

Repository subdirectory that contains .cloudeval/config.yaml and the IaC source files.

boolean

Allows review to continue when the working tree has local changes. Use only for deliberate generated-file workflows.

boolean

Returns deterministic gate and report data without the AI-written review summary.

object

required

Project id and name used for the review.

string

Repository resolved for the review.

string

Branch or ref resolved for the review.

string

Commit reviewed by the command.

object

required

GitHub sync submission and final status when the command waits for sync.

object

required

Cost, architecture, preload, and graph report availability used by the review.

object

required

Evaluated gate result from .cloudeval/config.yaml and available reports. data.gate.status controls whether the command exits successfully.

object

AI review summary status and content when summary generation is enabled.

string

required

Reviewer-facing Markdown summary included in JSON output and written to review.md when --output is used.

Ask a grounded project question

cloudeval ask "What changed in this project?" \
  --project "$PROJECT_ID" \
  --format json \
  --non-interactive

string

required

Required positional prompt. Quote it when it contains spaces or shell punctuation.

string

Project id used to ground the answer. If omitted, the CLI uses the active profile default project when one is configured.

string

Existing thread id when you want the answer to continue prior context.

string

Model override. Omit it to use the active profile default.

string

Output format: text, json, ndjson, or markdown. Defaults to text; --json is a shortcut for --format json.

string

Progress channel: auto, stderr, ndjson, or none. Defaults to auto.

string

required

Final answer text returned by Cloudeval.

string

required

Conversation id that can be resumed with --thread.

object

required

Project id and name used for the answer.

Run and export reports

cloudeval reports run \
  --project "$PROJECT_ID" \
  --type all \
  --wait \
  --format json

cloudeval reports download \
  --project "$PROJECT_ID" \
  --type all \
  --view parsed \
  --output ./reports \
  --format json

string

Project id whose reports should run or download. If omitted, authenticated CLI sessions use the Playground project when present, otherwise the first accessible project.

string

Report family: cost, waf, architecture, unit-tests, or all. Defaults to all.

string

Cost report region. Defaults to eastus.

string

Cost report currency. Defaults to USD.

boolean

Polls until report generation finishes instead of returning after the job is submitted.

number

Poll interval in milliseconds when --wait is set. Defaults to 2500 and is clamped to at least 500.

string

Download payload view: raw, parsed, or formatted. Defaults to raw.

string

File or directory path where JSON output or downloaded report payloads are written.

string

required

Project id used for the report operation.

string

required

Report type requested by reports run.

array

required

Report jobs submitted by reports run.

array

Job ids extracted from submitted report jobs.

array

Final report job statuses when reports run --wait is used.

array

Files written by reports download when output targets a directory.

Generate MCP client configuration

cloudeval mcp setup codex --dry-run --toolset readonly --format json

string

required

Required positional client: codex, claude, cursor, vscode, or generic.

boolean

Prints the configuration without writing to the client config file.

string

Cloudeval command path for the MCP client. Defaults to cloudeval.

string

Scope exposed to the generated MCP client config: all, readonly, projects, reports, or billing. Defaults to readonly.

string

Explicit client config path when the default location should not be used.

string

required

Normalized MCP client selected for setup.

string

required

MCP transport, currently stdio.

string

required

Command the MCP client should run, usually cloudeval.

array

required

Arguments for stdio server startup, usually ['mcp', 'serve'] plus any toolset flags.

string

Client config path when Cloudeval can infer one or when --config-path is provided.

boolean

required

Whether the command printed config only instead of writing files.

string

File written when setup is allowed to modify the client config.

Top-level and terminal UI

Command	Use it for	Key options
`cloudeval`	Open the terminal UI	none
`cloudeval tui`	Open the terminal UI explicitly	`--tab`, `--project`, `--health-check`, `--model`, `--profile`
`cloudeval tui --tab reports --project <project-id>`	Jump straight into a project report view	`--tab` values: `chat`, `overview`, `reports`, `projects`, `connections`, `billing`, `options`, `help`

Local setup and profiles

Command	Use it for	Key options
`cloudeval setup`	Configure CLI defaults interactively	`--profile`, `--base-url`, `--frontend-url`, `--project`, `--model`
`cloudeval setup --non-interactive`	Configure defaults in CI or agent setup	`--profile`, `--base-url`, `--frontend-url`, `--project`, `--model`, `--format`
`cloudeval config show`	Show current profile settings	`--profile`, `--format`, `--output`
`cloudeval config get <key>`	Read one setting	`baseUrl`, `frontendUrl`, `defaultProjectId`, `model`, `outputFormat`
`cloudeval config set <key> <value>`	Set one profile setting	`--profile`, `--format`
`cloudeval config unset <key>`	Remove one profile setting	`--profile`, `--format`
`cloudeval config path`	Print the settings file path	`--profile`
`cloudeval config profiles`	List local profiles	`--format`

Example agent setup:

cloudeval setup \
  --non-interactive \
  --profile codex \
  --project <project-id> \
  --model gpt-5-nano \
  --format json

Explicit flags still win over profile defaults. For example, cloudeval ask ... --project <id> uses that project even if the active profile has a different defaultProjectId.

Authentication

Command	Use it for	Notes
`cloudeval login`	Browser-based sign-in	Best for normal workstations
`cloudeval login --headless`	Device-code sign-in	Best for SSH or headless terminals
`cloudeval auth status`	Inspect current auth state	Shows token cache, credential storage, service URL, and stored session metadata
`cloudeval logout`	Clear local auth	Ends the local session
`cloudeval logout --all-devices`	Revoke all CLI sessions	Use when you want to force a broader sign-out

Chat and one-shot questions

Command	Use it for	Key options
`cloudeval chat`	Interactive terminal chat	`--conversation`, `--continue`, `--resume`, `--model`, `--machine`, `--debug`, `--profile`
`cloudeval ask "<question>"`	One grounded answer	`--project`, `--thread`, `--model`, `--profile`, `--format`, `--progress`, `--non-interactive`, `--print-url`, `--no-open`, `--output`
`cloudeval agent "<task>"`	Freeform agent-mode task	`--project`, `--thread`, `--model`, `--profile`, `--format`, `--progress`, `--non-interactive`, `--no-hooks`
`cloudeval review`	Review a GitHub-backed project from the current pushed commit	`--project`, `--repo`, `--ref`, `--commit-sha`, `--source-root`, `--config`, `--no-wait`, `--wait-timeout`, `--poll-interval`, `--no-ai-summary`, `--ai-summary-mode`, `--ai-summary-profile`, `--ignore-dirty`, `--format`, `--output`, `--non-interactive`

ask supports:

--format text|json|ndjson|markdown
--progress auto|stderr|ndjson|none
--json as a shortcut for JSON output

Use ask in scripts. Use chat when the session needs back-and-forth context. Successful ask runs are recorded in local session history. review is for GitHub-backed Infrastructure as code projects. It resolves the current GitHub repository, syncs the pushed commit to the linked CloudEval project, waits for sync/report refresh by default, reads latest cost and architecture reports, includes Well-Architected, cost, and validation drill-downs, includes an AI-written summary, and evaluates .cloudeval/config.yaml ci.gates when present. It stops before any API call if the local working tree is dirty:

Reviews pushed commits only. Add --ignore-dirty to review HEAD anyway.

Use --ignore-dirty only when intentionally reviewing the current HEAD while generated local files are present. Use --no-wait only when you want to submit sync and return before reports finish. Use --no-ai-summary when automation should output deterministic gate/report data only. Use --ai-summary-mode agent --ai-summary-profile architecture to generate the narrative through an Agent Profile instead of the default ask mode. Resume previous work:

cloudeval chat --continue --profile codex
cloudeval chat --resume <thread-id-or-title> --profile codex
cloudeval ask "Follow up on this thread" --thread <thread-id> --profile codex --format json --non-interactive

Agent Profiles

Command	Use it for	Key options
`cloudeval agents list`	List CloudEval Agent Profiles	`--profile`, `--format`, `--output`
`cloudeval agents show <profile-id>`	Inspect one Agent Profile	`--profile`, `--format`, `--output`
`cloudeval agents run <profile-id> [prompt]`	Run a named reviewer against a CloudEval project	`--project`, `--thread`, `--model`, `--format`, `--no-hooks`

Public profile ids and names are single-word labels: architecture, cost, triage, and remediation. Architecture includes the Well-Architected review lens, so there is no separate Well-Architected Agent Profile. Agent Profiles are separate from local CLI config profiles. When agents run omits [prompt], CloudEval uses a starter prompt for the selected project source and profile mode: template or live sync, ask or agent. The starter is deterministic for automation. CloudEval applies the selected profile’s focus, tool priorities, and response style server-side. See Agent and automation rules for the shared Chat, CLI, and MCP behavior. Quick examples:

cloudeval agents run architecture "What needs attention first?" --project <project-id>
cloudeval agents run cost "What needs attention first?" --project <project-id>
cloudeval agents run triage "What needs attention first?" --project <project-id>
cloudeval agents run remediation "What needs attention first?" --project <project-id>

The prompt can stay the same. The selected Agent Profile changes the evidence CloudEval prioritizes and the shape of the answer: architecture tradeoffs, cost signals, incident triage, or remediation sequencing.

Local session history

Command	Use it for	Key options
`cloudeval sessions list`	List local CLI sessions for the active profile	`--profile`, `--limit`, `--format`, `--output`
`cloudeval sessions get <thread-id>`	Inspect one local session	`--profile`, `--format`, `--output`
`cloudeval sessions search <query>`	Search local sessions by title, project, or message text	`--profile`, `--limit`, `--format`, `--output`
`cloudeval sessions rename <thread-id> <title>`	Give a local session a memorable title	`--profile`, `--format`, `--output`
`cloudeval sessions export`	Export local session history	`--profile`, `--format`, `--output`
`cloudeval sessions delete <thread-id>`	Delete one local session	`--profile`, `--yes`, `--format`
`cloudeval sessions prune`	Delete old local sessions	`--profile`, `--older-than`, `--yes`, `--format`

Session history is local to the machine and scoped by profile. Pass --yes for delete and prune operations in automation. Common session workflow:

cloudeval sessions search "cost risk" --profile codex --format json
cloudeval sessions rename <thread-id> "Cost risk review" --profile codex --format json
cloudeval chat --resume "Cost risk review" --profile codex

Models

Command	Use it for	Key options
`cloudeval models list`	List CloudEval-supported models, with a local fallback catalog	`--profile`, `--base-url`, `--format`
`cloudeval models default get`	Show the configured default model	`--profile`, `--format`
`cloudeval models default set <model>`	Set the configured default model	`--profile`, `--format`

ask, chat, and tui use the profile’s configured model when --model is not passed.

Diagnostics

Command	Use it for	Key options
`cloudeval status`	Show profile, config, auth, service URL, and Node.js status	`--profile`, `--base-url`, `--format`
`cloudeval doctor`	Diagnose local CLI setup	`--profile`, `--base-url`, `--deep`, `--mcp`, `--format`

Use doctor --deep when you want a best-effort CloudEval service reachability check in addition to local config and auth storage checks. Use doctor --mcp before registering CloudEval with an MCP-compatible client:

cloudeval doctor --mcp --format json

MCP server

Command	Use it for	Key options
`cloudeval mcp status`	Show MCP server capabilities	`--format`, `--output`
`cloudeval mcp setup <client>`	Generate or install MCP client configuration	`codex`, `claude`, `cursor`, `vscode`, `generic`, `--dry-run`, `--command`, `--toolset`, `--config-path`, `--format`, `--output`
`cloudeval mcp serve`	Run CloudEval as a stdio MCP server	`--toolset`, `--base-url`, `--frontend-url`, `--machine`, `--verbose`, global `--profile`

Use MCP server mode when an agent framework can speak the Model Context Protocol directly and you do not want to parse shell output. Codex example:

cloudeval mcp setup codex --dry-run
codex mcp add cloudeval -- cloudeval mcp serve

Claude Desktop and Cursor examples:

cloudeval mcp setup claude --dry-run
cloudeval mcp setup cursor --dry-run
cloudeval mcp setup vscode --dry-run

mcp setup --toolset accepts all, readonly, projects, reports, or billing. For graph or validation toolsets, configure the client to run cloudeval mcp serve --toolset graph or --toolset validation directly. Generic MCP client example:

cloudeval mcp setup generic --dry-run --toolset readonly --format json

Use the generic output for MCP-compatible clients that accept an mcpServers JSON config. For Ollama-powered agents, configure the agent host launched by Ollama, such as a local coding agent or editor extension, with the generated CloudEval stdio entry. Focused toolsets:

Toolset	Best for
`all`	Full CloudEval MCP surface
`readonly`	Read-only project, report, billing, 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
`graph`	Project graph reads, timeline, diff, sync runs, and insights
`validation`	Template validation, parsing, and validation rule catalog reads

Example:

cloudeval mcp serve --toolset readonly

JSON-configured client example:

{
  "mcpServers": {
    "cloudeval": {
      "command": "cloudeval",
      "args": ["mcp", "serve"]
    }
  }
}

Current MCP tools:

ask
capabilities_get
agent_profiles_list
agent_profiles_get
agent_profiles_run
projects_list
projects_get
projects_export_diagram
projects_graph_get
projects_graph_timeline
projects_graph_diff
projects_graph_insights
projects_graph_sync_runs
template_validate
template_test
template_parse
rules_categories
rules_search
rules_get
reports_list
reports_run
reports_download
billing_summary
billing_usage
billing_ledger
open_url

MCP resources:

cloudeval://capabilities
cloudeval://projects
cloudeval://billing/summary
cloudeval://reports/latest

MCP prompts:

cloudeval-cloud-cost-review
cloudeval-architecture-review
cloudeval-template-preflight
cloudeval-template-release-gate
cloudeval-graph-drift-watch
cloudeval-impact-analysis
cloudeval-billing-review

Important notes:

The transport is stdio.
Use stored cloudeval login auth, stored cloudeval login --headless auth, or --machine.
Run login before starting mcp serve; stdin is reserved for MCP JSON-RPC messages.
--verbose writes diagnostics to stderr and keeps stdout reserved for the MCP protocol.
Use focused toolsets when an assistant should only see a smaller set of CloudEval capabilities.

Projects

Command	Use it for	Key options
`cloudeval projects list`	List projects	`--format`, `--open`, `--print-url`
`cloudeval projects get <project-id>`	Inspect one project	`--format`, `--output`
`cloudeval projects open <project-id>`	Open the matching app page	`--view`, `--layout`, `--print-url`, `--no-open`
`cloudeval projects export-diagram <project-id>`	Export an architecture or dependency diagram image	`--layout`, `--format`, `--labels`, `--output`, `--headers-output`, `--public`, `--frontend-url`
`cloudeval projects create`	Create a project from a template, IaC folder, or Cloud sync credentials	`--template-file`, `--template-url`, `--workspace-dir`, `--workspace-entry`, `--cloud-sync`, `--azure-*`, `--resource-group`, `--name`, `--description`, `--provider`

projects create returns the created project, connection metadata, sync status, and normalized template context where available. It supports four source modes. Use exactly one source per command:

--template-file for a local single ARM JSON template.
--template-url for a raw or GitHub ARM template URL.
--workspace-dir for a folder with nested or linked ARM templates.
--cloud-sync for a live Azure inventory project from scoped credentials.

Create from a local ARM JSON file:

cloudeval projects create \
  --template-file ./azuredeploy.json \
  --name "Azure quickstart import" \
  --provider azure \
  --profile codex \
  --format json \
  --output ./cloudeval-project.json

Create directly from an Azure Quickstart GitHub URL:

cloudeval projects create \
  --template-url https://github.com/Azure/azure-quickstart-templates/blob/master/quickstarts/microsoft.compute/1vm-2nics-2subnets-1vnet/azuredeploy.json \
  --name "Azure quickstart import" \
  --provider azure \
  --profile codex \
  --format json \
  --output ./cloudeval-project.json

Capture the IDs for follow-up commands:

PROJECT_ID=$(jq -r '.data.project.id' ./cloudeval-project.json)
CONNECTION_ID=$(jq -r '.data.connection.id' ./cloudeval-project.json)

cloudeval projects get "$PROJECT_ID" --profile codex --format json
cloudeval connections get "$CONNECTION_ID" --profile codex --format json

Create a nested ARM workspace project:

cloudeval projects create \
  --workspace-dir ./infra \
  --workspace-entry azuredeploy.json \
  --name "Nested ARM workspace" \
  --provider azure \
  --profile codex \
  --format json \
  --output ./cloudeval-project.json

PROJECT_ID=$(jq -r '.data.project.id' ./cloudeval-project.json)

cloudeval projects get "$PROJECT_ID" --profile codex --format json
cloudeval projects graph "$PROJECT_ID" --profile codex --format json --non-interactive
cloudeval reports run --project "$PROJECT_ID" --type all --wait --profile codex --format json

Create a Cloud sync project:

cloudeval projects create \
  --cloud-sync \
  --azure-tenant-id "$AZURE_TENANT_ID" \
  --azure-client-id "$AZURE_CLIENT_ID" \
  --azure-client-secret "$AZURE_CLIENT_SECRET" \
  --azure-subscription-id "$AZURE_SUBSCRIPTION_ID" \
  --resource-group rg-app \
  --name "Production Cloud sync" \
  --profile codex \
  --format json \
  --output ./cloudeval-project.json

PROJECT_ID=$(jq -r '.data.project.id' ./cloudeval-project.json)

cloudeval projects get "$PROJECT_ID" --profile codex --format json
cloudeval projects graph sync-runs "$PROJECT_ID" --profile codex --format json --non-interactive
cloudeval reports run --project "$PROJECT_ID" --type all --wait --profile codex --format json

Project graph intelligence

Use graph commands when automation needs project topology, sync history, graph diffs, or focused impact analysis without opening the web app.

Command	Use it for	Key options
`cloudeval projects graph <project-id>`	Read the current project graph	`--sync-version`, `--as-of`, `--include-diff`, `--format`, `--output`
`cloudeval projects graph timeline <project-id>`	List retained graph snapshots	`--limit`, `--format`, `--output`
`cloudeval projects graph diff <project-id>`	Compare two sync versions	`--from`, `--to`, `--format`, `--output`
`cloudeval projects graph insights <project-id>`	Ask for graph-derived insights	`—focus overview	impact	critical-paths	security	cost	changes`,` —resource`,` —limit`
`cloudeval projects graph sync-runs <project-id>`	List sync runs for automation gates	`--limit`, `--format`, `--output`

cloudeval projects graph "$PROJECT_ID" --format json --non-interactive
cloudeval projects graph insights "$PROJECT_ID" --focus overview --format json --non-interactive
cloudeval projects graph sync-runs "$PROJECT_ID" --format json --non-interactive

If a project has no retained graph snapshot or no materialized insight payload, the graph commands return the available graph metadata and the insights command returns a clear service error. Use sync-runs first when building automation that depends on graph history.

Template validation and rule catalog

Use validation commands before opening a pull request, merging infrastructure changes, or letting an agent continue with a deployment plan.

Command	Use it for	Key options
`cloudeval validate template`	Run cloud template validation checks	`--template-file`, optional `--parameters-file`, repeatable `--rule`, `--details`, `--wait`, `--progress`, `--poll-interval`, `--wait-timeout`, `--failed-only`, `--category`, `--pillar`, `--min-severity`, `--max-results`
`cloudeval validate tests`	Run the template test suite and return per-test details	`--template-file`, optional `--parameters-file`, repeatable `--test`, repeatable `--skip-test`, `--category`, repeatable `--group`, `--wait`, `--progress`, `--poll-interval`, `--wait-timeout`, `--verbose`
`cloudeval validate parse`	Parse a cloud template into resolved resources	`--template-file`, optional `--parameters-file`, `--location`
`cloudeval rules categories`	List validation check categories	`--format`, `--output`
`cloudeval rules search <query>`	Search the validation rule catalog	`--category`, `--pillar`, `--format`, `--output`
`cloudeval rules show <rule-id>`	Inspect one validation check	`--format`, `--output`

--parameters-file is optional on validate template, validate tests, and validate parse. Pass it when your template depends on parameter values; omit it when defaults are enough. Use rules search or rules show to find a validation check id, then pass one or more --rule values to run only those checks. Use --details when you need frontend-style per-check evidence in automation: rule id, status, severity, target resource, description, synopsis, recommendation, and documentation URL when available. Use --wait when the backend returns an async validation job and you want the CLI to poll until final results are ready. Pair it with --wait-timeout in automation so the gate fails instead of hanging indefinitely. Add --progress stderr for human-readable wait progress or --progress ndjson for machine-readable progress events on stderr. Final command data remains on stdout, so --format json and --format ndjson stay pipeable. Completed progress includes failing check/test details such as message, recommendation, severity, and file/template or resource location when available. If a completed backend result only has a worker-local temp file path, CloudEval reports the submitted template filename instead.

curl -fsSL \
  https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json \
  -o azuredeploy.json

curl -fsSL \
  https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.parameters.json \
  -o azuredeploy.parameters.json

cloudeval validate template \
  --template-file azuredeploy.json \
  --parameters-file azuredeploy.parameters.json \
  --rule <check-id> \
  --details \
  --wait \
  --progress stderr \
  --wait-timeout 600000 \
  --format json \
  --non-interactive

cloudeval validate tests \
  --template-file azuredeploy.json \
  --parameters-file azuredeploy.parameters.json \
  --wait \
  --progress stderr \
  --wait-timeout 600000 \
  --format json \
  --non-interactive

cloudeval validate parse \
  --template-file azuredeploy.json \
  --parameters-file azuredeploy.parameters.json \
  --format json \
  --non-interactive

cloudeval rules search "public network" --format json --non-interactive

Connections

Command	Use it for	Key options
`cloudeval connections list`	List existing connections	`--format`, `--open`, `--print-url`
`cloudeval connections get <connection-id>`	Inspect one connection	`--format`, `--output`
`cloudeval connections open <connection-id>`	Open the matching app page	`--print-url`, `--no-open`

The CLI does not currently expose a general connections create command. Use cloudeval projects create when you want to create the connection and project together from a template file, template URL, IaC folder, or Cloud sync credentials. Use the web app when you need to edit an existing connection.

Reports

Command	Use it for	Key options
`cloudeval reports list`	List reports for a project	`--project`, `--kind` values: `cost`, `waf`, `all`
`cloudeval reports run`	Start a report run	`--project`, `--type`, `--wait`, `--region`, `--currency`, `--no-save-report`, `--poll-interval`
`cloudeval reports cost`	View the current cost report	`--project`, `--period`, `--view`
`cloudeval reports waf`	View the current architecture report	`--project`, `--report`, `--severity`, `--view`
`cloudeval reports rules`	List rules behind architecture findings	`--type waf`
`cloudeval reports show <report-id>`	Inspect one saved report	`--format`, `--raw`, `--parsed`, `--formatted`
`cloudeval reports download`	Export report payloads	`--project`, `--type`, `--view`, `--timestamp`, `--output`

Current report run types:

cost
waf
architecture
unit-tests
all

Current download types:

cost
waf
architecture
all

Current payload views:

raw
parsed
formatted

Important report notes:

reports run --type architecture and reports run --type waf both target the architecture or Well-Architected report family.
reports download --type all can write multiple files when the output target is a directory.
reports download --type architecture maps to the architecture or WAF-style payload for that project.
Report commands support --open, --print-url, and --no-open when you want the corresponding app page.

Run and export all available reports for a project:

cloudeval reports run \
  --project "$PROJECT_ID" \
  --type all \
  --wait \
  --profile codex \
  --format json

cloudeval reports list \
  --project "$PROJECT_ID" \
  --kind all \
  --profile codex \
  --format json

cloudeval reports cost \
  --project "$PROJECT_ID" \
  --profile codex \
  --format markdown

cloudeval reports waf \
  --project "$PROJECT_ID" \
  --profile codex \
  --format markdown

cloudeval reports download \
  --project "$PROJECT_ID" \
  --type all \
  --view parsed \
  --output ./reports \
  --profile codex \
  --format json \
  --non-interactive

Issues inventory

Command	Use it for	Key options
`cloudeval issues list`	List cross-project issues inventory items	`--project`, `--type`, `--severity`, `--pillar`, `--category`, `--resource-type`, `--q`, `--min-monthly-savings`, `--sort`, `--limit`, `--offset`, `--allow-full-scan`
`cloudeval issues get <item-id>`	Fetch one issues inventory item by stable id	`--project`, `--allow-full-scan`, `--format`
`cloudeval issues open`	Open the Issues page in the browser	`--project`, `--type`, `--severity`, `--q`, `--sort`, `--print-url`, `--no-open`
`cloudeval open issues`	Same frontend target as `issues open`	`--project`, `--severity`, `--type`, `--q`, `--sort`, `--print-url`, `--no-open`
`cloudeval actions list	get	open`	Deprecated alias for `issues`	same as `issues`
`cloudeval open action-center`	Deprecated alias for `open issues`	same as `open issues`

List architecture findings, cost opportunities, and unit-test failures across projects:

cloudeval issues list \
  --type architecture,cost,unit-tests \
  --severity critical,high \
  --sort priority \
  --limit 50 \
  --format json

cloudeval issues get arch:project-1:rule-42 --format json

cloudeval issues open --severity critical --print-url --no-open

Filters and pagination

--type accepts architecture, cost, and unit-tests (comma-separated).
--sort accepts priority, severity, savings, or project (default priority).
--limit is page size 1-500 (default 50); use --offset for pagination.
--allow-full-scan is on by default for portfolio-wide queries; pass --no-allow-full-scan to require a --project filter on large portfolios.

API

GET /api/v1/issues/items reads materialized issues.latest.json per project.
Large portfolios: POST /api/v1/issues/scan, then GET /api/v1/issues/scan/{job_id}.
Deprecated API alias: GET /api/v1/action-center/items.

GitHub review automation

Use cloudeval review locally or from GitHub Actions when the project already exists and is linked to a GitHub repository through the CloudEval GitHub App:

cloudeval review \
  --project "$PROJECT_ID" \
  --format json \
  --output ./cloudeval-review \
  --non-interactive

In GitHub Actions, prefer the official action with mode: review; it forwards github.repository, github.ref_name, and github.sha for you. cloudeval review uses existing public CloudEval primitives: GitHub project sync, latest reports, AI summary generation, and config-driven gates. It does not require a separate low-level sync command.

App deeplinks

Use the open command group when you want a precise CloudEval app URL for human follow-up.

Command	Use it for	Key options
`cloudeval open overview`	Open app overview	`--print-url`, `--no-open`
`cloudeval open chat`	Open chat	`--thread`
`cloudeval open projects`	Open projects page or quick-create dialog	`--quick`, `--template-url`, `--name`, `--description`, `--provider`, `--auto-submit`
`cloudeval open project <project-id>`	Open a project workspace	`--view`, `--layout`, `--node`, `--resource`, `--tab`, `--file`, `--files`, `--cursor`, `--selection`, `--workspace-focus`, `--presentation`
`cloudeval open connections`	Open connections page	`--dialog`
`cloudeval open connection <connection-id>`	Open one connection	`--print-url`, `--no-open`
`cloudeval open reports`	Open reports with filters	`--project`, `--tab`, `--report-type`, `--time-range`, `--persona`, `--cadence`, `--issues-query`, `--issues-fullscreen`, `--issues-view`, `--download-pdf`
`cloudeval open billing`	Open subscription and usage views	`--tab` values: `plans`, `usage`, `billing`

Headless diagram image downloads

Use the native CLI command when CLI, CI, or MCP agents need diagram bytes directly instead of a browser tab.

export CLOUDEVAL_BASE_URL="${CLOUDEVAL_BASE_URL:-https://cloudeval.ai}"
export PROJECT_ID="<project-id>"

cloudeval projects export-diagram "$PROJECT_ID" \
  --layout architecture \
  --format png \
  --labels all \
  --output architecture.png \
  --headers-output architecture.headers \
  --base-url "$CLOUDEVAL_BASE_URL" \
  --non-interactive

cloudeval projects export-diagram "$PROJECT_ID" \
  --public \
  --layout dependency \
  --format svg \
  --labels viewport \
  --output public-dependency.svg \
  --headers-output public-dependency.headers \
  --non-interactive

Supported variants are --layout architecture|dependency, --format png|jpeg|svg, and --labels all|viewport. The frontend defaults to https://cloudeval.ai; pass --frontend-url only for local/dev frontends. Public/share graph exports require explicit --public; private exports use cloudeval login, cloudeval login --headless, or --machine. Human output and --json output report resolved absolute filesystem paths for the image and headers files. See Headless diagram image downloads for the full command set and security checks.

Billing and credits

Command	Use it for	Key options
`cloudeval credits`	Inspect current credit status	`--format`, `--print-url`
`cloudeval billing summary`	Inspect overall billing state	`--format`, `--print-url`
`cloudeval billing plans`	List plan metadata	`--format`, `--print-url`
`cloudeval billing usage`	Usage summary over time	`--range`, `--start-at`, `--end-at`, `--granularity`, `--action-type`, `--model`, `--outcome`, `--charge-status`
`cloudeval billing ledger`	Paged usage ledger	`--range`, `--start-at`, `--end-at`, `--action-type`, `--model`, `--outcome`, `--charge-status`, `--limit`, `--cursor`
`cloudeval billing invoices`	Billing invoice metadata	`--limit`
`cloudeval billing topups`	Top-up pack metadata	`--limit`
`cloudeval billing notifications`	Billing notices	`--limit`

Capability discovery and shell setup

Command	Use it for
`cloudeval capabilities --format json`	Discover supported commands, formats, deeplinks, and exit codes
`cloudeval help agents`	Read the CLI contract for scripts and agents
`cloudeval completion <shell>`	Print shell completion script (`bash`, `zsh`, `fish`, `powershell`)
`cloudeval completion install --shell <shell>`	Install shell completion in a standard per-user path
`cloudeval completion uninstall --shell <shell>`	Remove installed shell completion script

Commands not to assume

Do not assume these top-level commands exist unless a current capability check confirms them:

cloudeval init
cloudeval connect
cloudeval sync
cloudeval evaluate
cloudeval diagram
cloudeval report

Current practical mappings are:

Init -> cloudeval setup, cloudeval login, and cloudeval auth status
Import -> cloudeval projects create --template-file ... or cloudeval projects create --template-url ...
Status and local health -> cloudeval status and cloudeval doctor
Evaluate -> cloudeval reports run
Diagram -> cloudeval open project --view preview --layout architecture|dependency
Report retrieval -> cloudeval reports ...

Next step

Use Agent and automation rules if you are consuming the CLI from scripts, or Automate evaluations with the CLI for end-to-end examples.

CLI quickstart

Automation and agents

CLI reference

Structured command help

Top-level and terminal UI

Local setup and profiles

Authentication

Chat and one-shot questions

Agent Profiles

Local session history

Models

Diagnostics

MCP server

Projects

Project graph intelligence

Template validation and rule catalog

Connections

Reports

Issues inventory

GitHub review automation

App deeplinks

Headless diagram image downloads

Billing and credits

Capability discovery and shell setup

Commands not to assume

Next step

​Structured command help

​Top-level and terminal UI

​Local setup and profiles

​Authentication

​Chat and one-shot questions

​Agent Profiles

​Local session history

​Models

​Diagnostics

​MCP server

​Projects

​Project graph intelligence

​Template validation and rule catalog

​Connections

​Reports

​Issues inventory

​GitHub review automation

​App deeplinks

​Headless diagram image downloads

​Billing and credits

​Capability discovery and shell setup

​Commands not to assume

​Next step

Structured command help

Top-level and terminal UI

Local setup and profiles

Authentication

Chat and one-shot questions

Agent Profiles

Local session history

Models

Diagnostics

MCP server

Projects

Project graph intelligence

Template validation and rule catalog

Connections

Reports

Issues inventory

GitHub review automation

App deeplinks

Headless diagram image downloads

Billing and credits

Capability discovery and shell setup

Commands not to assume

Next step