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 backend URLs, frontend URLs, default projects, and model defaults for different agents, environments, or workspaces.

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 \
  --base-url https://cloudeval.ai/api/proxy/v1 \
  --frontend-url https://cloudeval.ai \
  --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, API 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`

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. 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

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 backend-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, backend 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 backend 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`, `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

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

Example:

cloudeval mcp serve --toolset readonly

JSON-configured client example:

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

Current MCP tools:

ask
projects.list
projects.get
reports.list
reports.run
reports.download
billing.summary
billing.usage
billing.ledger
open.url
capabilities.get

MCP resources:

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

MCP prompts:

cost-review
waf-triage
architecture-review
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 file or URL	`--template-file`, `--template-url`, `--parameters-file`, `--parameters-url`, `--name`, `--description`, `--provider`

projects create returns the created project, connection metadata, sync status, and normalized template context where available. 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

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. Some connection setup flows remain web-app oriented.

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

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.

Start here

Agents and MCP

Reference

Top-level and terminal UI

Local setup and profiles

Authentication

Chat and one-shot questions

Local session history

Models

Diagnostics

MCP server

Projects

Connections

Reports

App deeplinks

Headless diagram image downloads

Billing and credits

Capability discovery and shell setup

Commands not to assume

Next step

Start here

Agents and MCP

Reference

Documentation Index

​Top-level and terminal UI

​Local setup and profiles

​Authentication

​Chat and one-shot questions

​Local session history

​Models

​Diagnostics

​MCP server

​Projects

​Connections

​Reports

​App deeplinks

​Headless diagram image downloads

​Billing and credits

​Capability discovery and shell setup

​Commands not to assume

​Next step

Top-level and terminal UI

Local setup and profiles

Authentication

Chat and one-shot questions

Local session history

Models

Diagnostics

MCP server

Projects

Connections

Reports

App deeplinks

Headless diagram image downloads

Billing and credits

Capability discovery and shell setup

Commands not to assume

Next step