Skip to main content

npm versionnpm downloadsGitHub release downloadsrelease health

CloudEval CLI is the terminal surface for CloudEval AI. It is designed for developers, cloud engineers, platform teams, and agents that need repeatable workflows and scriptable output.
CloudEval terminal UI showing project-aware chat, reasoning progress, project context, model, mode, and credit status

​
What the CLI is good at

  • project creation from ARM JSON or template URLs
  • report runs and saved report retrieval
  • one-shot grounded questions
  • billing and credit inspection
  • local setup profiles for agents and environments
  • local diagnostics and model discovery
  • searchable local session history for one-shot CLI questions
  • resumable terminal chat sessions
  • a local stdio MCP server for agent tools, resources, and prompts
  • exact app deeplinks for projects, reports, connections, chat, and billing
  • machine-readable output for automation

​
CLI vs web app

TaskBest surface
Import a template from a script or jobCLI
Run reports and save JSON outputCLI
Ask one grounded question in automationCLI
Expose CloudEval to an MCP-compatible agentCLI
Review a diagram visuallyWeb app
Explore reports interactivelyWeb app
Manage sharing and collaborationWeb app
Use a terminal-first interactive experiencecloudeval or cloudeval tui

​
Binaries and service defaults

CloudEval ships two binary names:
  • cloudeval
  • eva
For normal production use, the CLI already knows the CloudEval service and app URLs. Pass --base-url or --frontend-url only when you are targeting a self-hosted, staging, or local environment.

​
Interactive vs pipeable work

Run without arguments when you want the terminal UI: 
cloudeval
cloudeval tui
cloudeval tui --tab reports --project <project-id>
Use explicit subcommands when you want output that another tool can consume: 
cloudeval setup --non-interactive --profile codex --project <project-id> --model gpt-5-nano --format json
cloudeval doctor --profile codex --format json
cloudeval doctor --profile codex --mcp --format json
cloudeval ask "Summarize project risk" --project <project-id> --format json --non-interactive
cloudeval reports run --project <project-id> --type all --wait --format json
cloudeval projects list --format json

​
Profiles and local configuration

Use cloudeval setup when you want the CLI to remember defaults such as the CloudEval service URL, app URL, default project, and default model: 
cloudeval setup \
  --non-interactive \
  --profile codex \
  --project <project-id> \
  --model gpt-5-nano \
  --format json
Inspect or change those settings with: 
cloudeval config show --profile codex --format json
cloudeval config set model gpt-5-nano --profile codex --format json
cloudeval config path --profile codex
Profiles are selected with --profile <name> or CLOUDEVAL_PROFILE. Explicit command flags still override profile defaults.

​
Authentication modes

CloudEval supports three practical auth patterns:
  • Browser login with cloudeval login when your terminal can open a browser on the same machine
  • Headless device-code login with cloudeval login --headless when you are using SSH, a remote server, a container, or another terminal without a usable browser handoff
  • Machine or service access through --machine when service-principal credentials are configured
Useful auth commands: 
cloudeval login
cloudeval login --headless
cloudeval auth status
cloudeval logout
cloudeval logout --all-devices
cloudeval auth status shows whether you are authenticated, whether tokens are cached, where the CLI is storing credentials, the effective service URL, and any active session or account identifiers currently stored by the CLI.

​
Diagnostics, models, and sessions

Use diagnostics before relying on a local install in automation: 
cloudeval status --profile codex --format json
cloudeval doctor --profile codex --format json
cloudeval doctor --profile codex --deep --format json
Use model commands to discover CloudEval-supported models and set a default: 
cloudeval models list --profile codex --format json
cloudeval models default set gpt-5-nano --profile codex --format json
cloudeval models default get --profile codex --format json
Successful ask runs are saved to local profile-scoped session history: 
cloudeval sessions list --profile codex --format json
cloudeval sessions search "cost spike" --profile codex --format json
cloudeval sessions get <thread-id> --profile codex --format json
cloudeval sessions rename <thread-id> "Production cost review" --profile codex --format json
cloudeval sessions export --profile codex --format json
Resume a previous terminal conversation by title or thread ID: 
cloudeval chat --continue --profile codex
cloudeval chat --resume "Production cost review" --profile codex
cloudeval ask "Follow up on the same investigation" --thread <thread-id> --profile codex --format json --non-interactive

​
MCP server mode

CloudEval can also run as a local stdio MCP server when you want an agent tool to call CloudEval directly instead of shelling out to individual commands. Start the server: 
cloudeval mcp status --format json
cloudeval mcp serve
For Codex: 
cloudeval mcp setup codex --dry-run
codex mcp add cloudeval -- cloudeval mcp serve
For Claude Desktop and Cursor: 
cloudeval mcp setup claude --dry-run
cloudeval mcp setup cursor --dry-run
For JSON-configured MCP clients: 
cloudeval mcp setup generic --dry-run --toolset readonly --format json

{
  "mcpServers": {
    "cloudeval": {
      "command": "cloudeval",
      "args": ["mcp", "serve"]
    }
  }
}
For Ollama-powered agents, configure the MCP-capable host that Ollama launches. CloudEval does not need a separate Ollama bridge; the host only needs a stdio MCP entry that runs cloudeval mcp serve. Use focused toolsets when an agent does not need the full CloudEval surface: 
cloudeval mcp serve --toolset readonly
cloudeval mcp serve --toolset projects
cloudeval mcp serve --toolset reports
cloudeval mcp serve --toolset billing
Important behavior:
  • transport is stdio
  • auth can come from stored cloudeval login credentials, stored cloudeval login --headless credentials, or --machine
  • run login before starting mcp serve; stdin is reserved for MCP messages
  • doctor --mcp checks the local MCP discovery surface
  • the server exposes CloudEval tools for ask, projects, reports, billing, deeplinks, and capability discovery
  • MCP clients that support resources and prompts can discover project, billing, report, and review-oriented context directly

​
Output model

Machine-friendly commands support these formats:
  • text
  • json
  • ndjson
  • markdown
Report-oriented commands also support additional presentation formats such as summary, table, and tui. For automation, treat this as the contract:
  • stdout is for command data
  • stderr is for prompts, warnings, auth flow messages, and browser-open messages
  • cloudeval capabilities --format json is the current command source of truth

​
Exit codes

CloudEval exposes stable exit codes for automation:
  • 0: success
  • 1: expected failure
  • 2: usage error
  • 3: authentication required
  • 4: service unavailable
  • 5: object not found

​
Safe defaults

  • Prefer --format json for scripts.
  • Prefer --non-interactive in CI or agent workflows.
  • Prefer --profile <name> when multiple agents or environments share one machine.
  • Prefer --print-url --no-open when a command can generate a CloudEval app link.
  • Use cloudeval login --headless for SSH, containers, or remote terminals.
  • Use --machine only when service-principal machine authentication is configured.
  • Prefer focused MCP toolsets for assistants that only need read-only, project, report, or billing access.

​
Next step

Use CLI command reference for the current command surface, or Use the CLI if you want a working setup sequence first.
Last modified on June 22, 2026