cloudeval-cli

[![Cloudeval AI](https://cloudeval.ai/common/logo-abstract-cloud-dark-v3-ui.png)](https://cloudeval.ai)

<p align="center">
  <img src="docs/assets/images/cli/tui-chat.png" alt="Cloudeval CLI terminal UI" width="100%">
</p>

# Cloudeval CLI

**Your cloud, in the terminal: evaluated, reported, and agent-ready.**

[![Latest release](https://img.shields.io/github/v/release/ganakailabs/cloudeval-cli?sort=semver&style=flat-square&label=release)](https://github.com/ganakailabs/cloudeval-cli/releases/latest)
[![npm version](https://img.shields.io/npm/v/@ganakailabs/cloudeval-cli?style=flat-square&logo=npm)](https://www.npmjs.com/package/@ganakailabs/cloudeval-cli)
[![npm downloads](https://img.shields.io/npm/dm/@ganakailabs/cloudeval-cli?style=flat-square&logo=npm&label=npm%20downloads)](https://www.npmjs.com/package/@ganakailabs/cloudeval-cli)
[![GitHub downloads](https://img.shields.io/github/downloads/ganakailabs/cloudeval-cli/total?style=flat-square&logo=github&label=release%20downloads)](https://github.com/ganakailabs/cloudeval-cli/releases)
[![Release health](https://img.shields.io/github/actions/workflow/status/ganakailabs/cloudeval-cli/semantic-release.yml?branch=main&style=flat-square&label=release%20health)](https://github.com/ganakailabs/cloudeval-cli/actions/workflows/semantic-release.yml)
[![Cloudeval](https://img.shields.io/badge/product-Cloudeval-b6f23c?style=flat-square&labelColor=0b0f0a)](https://cloudeval.ai)
[![Docs](https://img.shields.io/badge/docs-docs.cloudeval.ai-2d6cdf?style=flat-square&logo=readthedocs&logoColor=white)](https://docs.cloudeval.ai/cli/get-started)
[![Discord](https://img.shields.io/badge/Discord-community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/tk5dcU2a7T)
[![Issues](https://img.shields.io/github/issues/ganakailabs/cloudeval-cli?style=flat-square&logo=github&label=issues)](https://github.com/ganakailabs/cloudeval-cli/issues)
[![AGENTS.md](https://img.shields.io/badge/contributors-AGENTS.md-555?style=flat-square)](https://github.com/ganakailabs/cloudeval-cli/blob/main/AGENTS.md)

Cloudeval CLI turns **ARM templates**, **GitHub-hosted IaC**, and **live Azure context** into cost, architecture, and Well-Architected signals. Use it as a terminal UI, a scriptable automation client, or an MCP server for Codex, Cursor, Claude, VS Code, and any stdio JSON-RPC client.

## Why Use It

| For                | What you get                                                                                                                      |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **Terminal users** | A full TUI with chat, Agent mode, workspace tabs, thread switching, slash commands, a context rail, task ledger, artifact chips, and local SQLite session history. |
| **Automation**     | Stable `json`, `ndjson`, `markdown`, and text output; payloads on stdout; progress and prompts on stderr; predictable exit codes. |
| **Agents and CI**  | Scoped access-key credentials, redacted output by default, MCP toolsets, recipes, and machine-readable capability metadata.       |

## Install

Node.js 20+ users can install from npm:

```bash
npm install -g @ganakailabs/cloudeval-cli
cloudeval --help
```

macOS, Linux, WSL2, Git Bash, and PowerShell 7+ on Windows or Linux can use
the standalone release installer:

```bash
curl -fsSL https://cli.cloudeval.ai/install.sh | bash
```

```powershell
irm https://cli.cloudeval.ai/install.ps1 | iex
```

Then reload your shell and sign in:

```bash
source ~/.bashrc   # or: source ~/.zshrc
cloudeval login
cloudeval status
cloudeval chat
```

Device login goes through **cloudeval.ai** and always asks the browser auth
provider to show the account chooser, so users can choose the intended work
email even when another account is already signed in. No local Azure app
registration is needed for normal CLI use.

<details>
<summary><strong>Installer behavior and controls</strong></summary>

The installer:

- downloads checksum-verified GitHub release assets and installs `cloudeval`;
- creates the `eva` and `cloud` aliases on non-Windows platforms;
- can install shell completions for bash, zsh, and fish;
- can offer concise MCP setup for detected Codex, Claude Desktop, Cursor, and VS Code clients, skipping clients where Cloudeval MCP is already configured and avoiding prompts when only manual-only setup remains;
- asks whether to share limited CLI telemetry, defaulting to yes; declining writes `telemetry.enabled=false`;
- explains credential setup but does not create access keys or write secrets into MCP client config;
- shows compact labeled progress bars in interactive terminals;
- uses connect/stall timeouts so slow CDN transfers fail clearly.

Useful controls:

```bash
curl -fsSL https://cli.cloudeval.ai/install.sh | CLOUDEVAL_INSTALL_AGENT_SETUP=0 bash
curl -fsSL https://cli.cloudeval.ai/install.sh | CLOUDEVAL_INSTALL_MCP_CLIENTS=codex,cursor bash
curl -fsSL https://cli.cloudeval.ai/install.sh | CLOUDEVAL_TELEMETRY=0 bash
```

```powershell
$env:CLOUDEVAL_ASSUME_YES = "1"
irm https://cli.cloudeval.ai/install.ps1 | iex
```

The bash installer can also detect agent clients and offer MCP setup. The
PowerShell installer installs the verified binary, `yoga.wasm`, license
notices, PATH, and optional PowerShell tab completions. Run `cloudeval mcp
setup` afterward when you want MCP client configuration.

</details>

## Telemetry

Cloudeval CLI sends curated custom events to Azure Application Insights by
default. Events cover command family, success, duration, safe option enums, CLI
version, Node/runtime version, OS major version, architecture, install source,
update/install outcomes, MCP tool names, and TUI launch/exit metadata. After
login, events may include the signed-in email and first/last/full name.

Telemetry never sends raw prompts, command output, tokens, local paths, project
or resource identifiers, account/session/tenant identifiers, cloud resource
names, stack traces, or raw error messages. Disable or re-enable it anytime:

```bash
cloudeval config set telemetry.enabled false
cloudeval config get telemetry.enabled --format json
cloudeval config set telemetry.enabled true
cloudeval config unset telemetry.enabled
```

Environment overrides take precedence for a single run:

```bash
CLOUDEVAL_TELEMETRY=0 cloudeval status --format json
CLOUDEVAL_TELEMETRY=1 cloudeval --help
```

Update later with:

```bash
cloudeval update --check
cloudeval update --yes
```

After an update, restart or reload configured MCP clients when you are ready to
load newly exposed Cloudeval tools, resources, or prompts. Cloudeval does not
restart Codex, Claude, Cursor, VS Code, or other MCP hosts automatically.

Uninstall local installer-owned artifacts while keeping Cloudeval config,
sessions, and auth by default:

```bash
cloudeval uninstall --dry-run
cloudeval uninstall --yes
cloudeval uninstall --yes --remove-config  # also removes ~/.config/cloudeval
npm uninstall -g @ganakailabs/cloudeval-cli # if installed through npm
```

## Start Here

```bash
cloudeval                         # Terminal UI
cloudeval tui --graph-diagram ascii
cloudeval ask "Summarize my cloud risk" --format json
cloudeval agent "Find cost and architecture risks" --format json
cloudeval agents list
cloudeval agents run cost --project <project-id> --format json
cloudeval recipes list
cloudeval projects list
cloudeval uninstall --dry-run
cloudeval projects graph insights <project-id> --focus impact --resource <resource-id> --format json
cloudeval validate template --template-file template.json --parameters-file parameters.json --rule <check-id> --details --wait --progress stderr --wait-timeout 600000 --format json
cloudeval validate tests --template-file template.json --parameters-file parameters.json --wait --progress stderr --wait-timeout 600000 --format json
cloudeval rules search "public network" --format json
cloudeval reports list
cloudeval actions list --type architecture,cost,unit-tests --format json
cloudeval actions open --print-url --no-open
cloudeval review --repo owner/repo --ref feature/infra-change --commit-sha <sha> --github-checks --sarif --output cloudeval-review --format json --non-interactive
cloudeval capabilities --format json
cloudeval doctor --deep
```

Full docs: [Get started with the CLI](https://docs.cloudeval.ai/cli/get-started) and [CLI command reference](https://docs.cloudeval.ai/cli/commands).

Inside the Terminal UI, use the Thread control or `/thread` to switch open chat
sessions, recent Cloudeval chat threads, and local CLI sessions. `/thread new`
starts another independent open session, and `/open` jumps to the same chat
thread in Cloudeval when the active session has a thread id. Roomy terminals show
a context rail with project, thread, model, mode, profile, report artifact
chips; narrower terminals keep the
chat first and expose the same controls through the composer and slash commands.
Typing `/` opens a bottom command completion strip; use Tab or Up/Down to move,
Right to accept the ghost text, and Enter to choose the highlighted command.
Streaming work appears as a task ledger in the thread, and the bottom composer
stays docked so prompt entry does not compete with the transcript. Grounded
answers show numbered citations and a Sources section instead of raw
`[S_tool_...]` tags, with citation numbers highlighted inline; `/copy` copies
the latest assistant response and `/download` writes a Markdown transcript with
the same references. Graph insight blocks render as bordered terminal cards
instead of exposing raw `graph-insight` markers; when a card contains a
conservative Mermaid flowchart, `--graph-diagram auto` renders a terminal
diagram in roomy TTYs, `unicode` or `ascii` force a mode, and `off` keeps the
Mermaid source fallback. Unsupported Mermaid syntax stays visible as source
instead of breaking the transcript. Negotiated chat vis