Command Reference
Complete reference for the CCA CLI. The binary is cca.

Resource IDs are redacted in the example images on this page.
Global Options
These options apply to every command (they may appear before or after the subcommand):
| Option | Short | Default | Description |
|---|---|---|---|
--help | -h | Show help information | |
--version | -V | Show version number | |
--verbose | -v | off | Enable console logging (logs are silent by default) |
--log-level | info | Log level: error, warn, info, debug, trace | |
--log-format | compact | Log format: json, pretty, compact | |
--log-file | Write logs to a file (enables logging regardless of --verbose) | ||
--mode | managed | Execution mode: managed, local (local requires an air-gapped build). Env: CCA_MODE | |
--api-key | API key for managed mode. Env: CCA_API_KEY | ||
--license-file | Path to a license file. Env: CCA_LICENSE_FILE | ||
--license-key | Base64-encoded license key. Env: CCA_LICENSE | ||
--bundle-path | Path to a signed rule bundle (air-gapped). Env: CCA_BUNDLE_PATH |
For managed mode you can avoid passing --api-key on every run — see login.
Commands
scan
Scan cloud resources for cost optimization opportunities.
cca scan [OPTIONS]
Options
| Option | Short | Default | Description |
|---|---|---|---|
--provider | -p | aws | Cloud provider: aws, azure |
--profile | AWS only: use this named profile from your AWS config. It wins over AWS_ACCESS_KEY_ID in the environment. Azure has no profiles: sign in with az login and choose the subscription with --account | ||
--account | The cloud account to scan. AWS: a guard. Your credentials decide the account, and the scan stops, before collecting anything, if they are for a different one. Azure: the subscription ID to scan (default: AZURE_SUBSCRIPTION_ID, then the Azure CLI default subscription). One account per scan | ||
--regions | -r | us-east-1 | Comma-separated regions, e.g. us-east-1,us-west-2 |
--services | -s | all | Comma-separated service categories: compute, storage, database, networking, serverless, analytics, containers, ai, security, monitoring, cdn, other |
--days | -d | 7 | Days of metrics to analyze |
--output | -o | table | Output format: table, json, yaml, markdown, csv, sarif, pdf |
--output-file | -f | stdout | Write output to a file |
--group-by-tags | Group findings by tag key for cost allocation (e.g. Team) | ||
--min-cost | Only include findings above this monthly USD amount | ||
--include-hygiene | false | Include $0-savings hygiene findings (hidden by default; High/Critical findings are always shown) | |
--all | false | Show all findings (default: top 10) | |
--top | Maximum number of findings to display | ||
--no-recommendations | false | Hide recommendations in output | |
--dump | Dump all raw data (resources, metrics, costs, findings) to a JSON file | ||
--summary | false | Summary only (default: detailed report with remediation) | |
--skip-costs | false | Skip cost collection (useful for cloud emulator testing) |
Global options (--mode, --api-key, …) also apply.
Examples
# Basic AWS scan (managed mode is the default)
cca scan --provider aws
# Scan specific regions
cca scan --provider aws --regions us-east-1,us-west-2
# Output as JSON to a file
cca scan --provider aws --output json --output-file results.json
# Show all findings, not just the top 10
cca scan --provider aws --all
# Filter resources by tag
# Only findings worth more than $50/mo
cca scan --provider aws --min-cost 50
# Use a named AWS profile, and refuse to run against any other account
cca scan --provider aws --profile production --account 123456789012
# Azure scan of one subscription
cca scan --provider azure --account 00000000-0000-0000-0000-000000000000
# Debug logging
cca scan --provider aws --log-level debug
Which account is scanned
Before collecting anything, scan prints the account it resolved on one line to stderr (so -o json output stays clean):
Scanning AWS account 123456789012 (demo) with profile demo, in us-east-1
Scanning Azure subscription 00000000-0000-0000-0000-000000000000 (Production) in tenant 11111111-1111-1111-1111-111111111111
If you pass --account and the credentials are for another AWS account, the scan stops with the account it found. If an Azure credential can see several subscriptions and none is selected, the scan lists them and stops: it never picks one for you. Environment variables (AWS_PROFILE, AZURE_SUBSCRIPTION_ID, and so on) keep working; the flags only override them. Run cca whoami to check the account without scanning.
Output Formats
- table (default) — human-readable console output.
- json — structured JSON for programmatic use.
- yaml — YAML equivalent of the JSON output.
- markdown — a Markdown report (handy for PRs / wikis).
- csv: one row per finding, for spreadsheets and FinOps workflows. Paid plans only (see below).
- sarif: SARIF 2.1.0, for CI code scanning (GitHub, GitLab). Upload with
github/codeql-action/upload-sarif. - pdf: a standalone PDF report. Paid plans only (see below).
csv and pdf export is a paid feature. On the Free plan the CLI runs the scan first and then stops with '<format>' export is a paid feature, because the service reports your plan only after the scan. The scan is saved; re-run with -o json or -o markdown for the same data, or upgrade to Professional.
Machine-readable formats (json, yaml, markdown, csv, sarif) print no progress noise, so they pipe cleanly.
Example output
The default table output leads with the executive summary above, then lists findings by severity — each with the evidence behind it and a remediation step:

audit
Generate a comprehensive infrastructure cost audit, with optional cost-allocation grouping, tag-compliance checks, and trend comparison against a previous run.
cca audit [OPTIONS]
Options
| Option | Short | Default | Description |
|---|---|---|---|
--provider | -p | aws | Cloud provider: aws, azure |
--regions | -r | us-east-1 | Comma-separated regions |
--services | -s | all | Comma-separated service categories (see scan) |
--days | -d | 7 | Days of metrics to analyze |
--output | -o | table | Output format: table, json, yaml, markdown, csv, sarif, pdf |
--output-file | -f | stdout | Write output to a file |
--group-by-tags | Group costs by these tag keys (comma-separated) | ||
--compare | Compare to a previous audit JSON for trend analysis | ||
--cost-threshold | Minimum cost (USD) to include in the breakdown | ||
--tag-policy | Path to a tag policy file (YAML/JSON) for compliance validation | ||
--required-tags | Required tag keys (comma-separated) — simpler alternative to --tag-policy | ||
--skip-tag-compliance | false | Skip tag compliance validation | |
--all | false | Show all findings (default: top 10) | |
--top | Maximum number of recommendations to display | ||
--dump | Dump all raw data to a JSON file | ||
--summary | false | Summary only | |
--skip-costs | false | Skip cost collection |
Examples
# Full audit grouped by team tag
cca audit --provider aws --group-by-tags team,environment
# Trend vs a previous run
cca audit --provider aws --output json --output-file this-week.json
cca audit --provider aws --compare this-week.json
# Enforce required tags
cca audit --provider aws --required-tags owner,cost-center
report
Generate reports from a saved data dump (produced by scan/audit --dump). No cloud access required.
cca report <DUMP_FILE> [OPTIONS]
Options
| Option | Short | Default | Description |
|---|---|---|---|
<DUMP_FILE> | required | Path to the data dump JSON file (positional) | |
--output | -o | table | Output format: table, json, yaml, markdown, csv, sarif, pdf |
--output-file | -f | stdout | Write output to a file |
--group-by-tags | Group costs by these tag keys (comma-separated) | ||
--compare | Compare to a previous audit JSON for trend analysis | ||
--cost-threshold | Minimum cost (USD) to include in the breakdown | ||
--severity | all | Filter by severity: critical, high, medium, low (comma-separated) | |
--regions | all | Filter by region (comma-separated) | |
--services | all | Filter by service (comma-separated) | |
--all | false | Show all findings (default: top 10) | |
--top | Maximum number of recommendations to display | ||
--summary | false | Summary only |
Examples
# Re-render a saved dump as Markdown, high severity only
cca report dump.json --severity critical,high --output markdown
demo
Show a sample report using built-in demo data. No account, no cloud credentials, and no network, so it is the fastest way to see what a report looks like before signing up or wiring up access.
cca demo [OPTIONS]
Options
| Option | Short | Default | Description |
|---|---|---|---|
--output | -o | table | Output format: table, json, yaml, markdown, csv, sarif |
--all | false | Show all findings (default: top 10) |
The sample banner and the "run a real scan" call to action print to stderr, so machine formats (--output json, etc.) stay clean on stdout.
Examples
# See the sample report
cca demo
# Every finding, as JSON (pipe-clean on stdout)
cca demo --all --output json
setup
Set up cloud provider access — generate or deploy a least-privilege read-only IAM role via CloudFormation.
cca setup [OPTIONS]
Options
| Option | Short | Default | Description |
|---|---|---|---|
--provider | -p | aws | Cloud provider: aws, azure |
--deploy | false | Deploy the CloudFormation stack (create the IAM role) | |
--output-template | false | Print the CloudFormation template | |
--stack-name | cloud-cost-analyzer-access | CloudFormation stack name | |
--role-name | CloudCostAnalyzerRole | IAM role name to create | |
--create-user | false | Also create an IAM user with access keys | |
--user-name | cloud-cost-analyzer | IAM user name (with --create-user) | |
--external-id | External ID for cross-account role assumption | ||
--trusted-account-id | Trusted AWS account ID (cross-account access) | ||
--output-file | -f | Write the template to a file | |
--region | -r | us-east-1 | AWS region for the deployment |
Examples
# Print the CloudFormation template
cca setup --provider aws --output-template
# Deploy the read-only role
cca setup --provider aws --deploy
doctor
Run preflight diagnostics — checks credentials, IAM permissions, and connectivity, and prints a clear pass/warn/fail report. Run this first when a scan fails or isn't reaching the dashboard.
cca doctor [OPTIONS]
Options
| Option | Short | Default | Description |
|---|---|---|---|
--provider | -p | aws | Cloud provider to diagnose: aws, azure |
--json | false | Emit results as JSON (for CI / machine parsing) |
doctor also reads the global --mode, --api-key / CCA_API_KEY, and stored credentials, so it validates the exact managed-mode setup a scan will use. It exits non-zero on hard failures, so it can gate automation.
Examples
# Diagnose the default AWS setup
cca doctor --provider aws
# Machine-readable output for CI
cca doctor --provider aws --json
whoami
Show which cloud account the next scan would use, without collecting anything, and whether the CLI is signed in to CCA. It resolves the account exactly as scan does and stops on the same errors.
cca whoami [OPTIONS]
Options
| Option | Short | Default | Description |
|---|---|---|---|
--provider | -p | aws | Cloud provider: aws, azure |
--profile | AWS only: use this named profile | ||
--account | The account to expect (AWS) or the subscription to use (Azure). A different AWS account is an error | ||
--json | false | Emit the result as JSON |
Example
$ cca whoami --profile demo
Cloud: AWS
Account: 123456789012 (demo)
Identity: arn:aws:iam::123456789012:user/alex
Credentials: profile demo
CCA: signed in
Service: https://cca.dragonfractal.com
The CCA plan is not shown here; the line printed after each scan reports it.
login
Sign in and store a free API key locally, so scans don't need --api-key (or CCA_API_KEY) on every run. The key is saved to ~/.cloud-cost-analyzer/credentials.json with owner-only (0600) permissions.
# Browser sign-in (Google, GitHub, or email). Opens a page, drops the key in place.
cca login
# Device-code flow: prints a link and a short code to enter on any other device.
# `cca login` picks this by itself over SSH or on a Linux machine with no display.
cca login --device
# Force the browser flow where it was not chosen (for example a desktop reached over SSH).
# The browser must run on this machine: the sign-in returns to a local listener.
cca login --browser
# CI, or any machine with an existing key: stored directly, no browser. Create a key on
# the API Keys page of the dashboard.
CCA_API_KEY=cca_live_xxxxx cca login
In CI with no terminal and no key, cca login stops straight away and tells you to set CCA_API_KEY, instead of waiting for an approval nobody can give. Getting started: quickstart.
The browser flow uses loopback + PKCE (the authorization code returns only to your own machine). New email/password accounts get a bounded free preview until the email is verified; Google/GitHub sign-ins are already verified.
Resolution precedence at scan time: --api-key flag > CCA_API_KEY env > stored credentials file.
logout
Sign out: revoke the API key cca login created on the server, then remove the locally stored copy.
cca logout
If the service cannot be reached, logout still removes the local copy, prints a warning that the key was not revoked, and exits 0. The key then stays valid until you delete it on the API Keys page. A key you created yourself on the API Keys page (for example one stored with cca login --api-key) is never revoked by logout, and logout tells you so. A key passed with --api-key or CCA_API_KEY is not touched either: logout only handles the stored key.
license
Manage the air-gapped license.
cca license <SUBCOMMAND>
| Subcommand | Description |
|---|---|
fetch <CODE> | Redeem an activation code and save the license locally |
show | Show the current license status |
path | Print the resolved license file path |
refresh-crl | Refresh the revocation-list cache for the current license |
# Redeem an activation code from the dashboard
cca license fetch ABCD-1234
# Check status
cca license show
upgrade
Unlock every finding (resource IDs, fixes, CSV/PDF export, CI gating) with a paid plan.
cca upgrade
Signed in (after cca login), it prints the billing link and opens it in your browser. Not signed in, it lists the steps: cca login, upgrade on the billing page, then scan again. Upgrading also unlocks the reports of scans you already ran. In CI or on a server, use an API key from the API Keys page in CCA_API_KEY instead of cca login.
update
Update the installed cca binary in place to the latest released version. It
downloads the matching build from the release server, verifies its checksum, and
replaces the running binary. Prints already the latest version when you are
current.
cca update
If cca is installed in a system directory (such as /usr/local/bin), the
replacement needs the same permissions you installed with, e.g. sudo cca update. See Updating for the full picture and the
reinstall fallback.
version
Show version information.
cca version
Output:
cloud-cost-analyzer 0.1.1
Environment Variables
The CLI reads these directly (see Environment Variables for the full list, including AWS/Azure credentials):
| Variable | Maps to |
|---|---|
CCA_API_KEY | --api-key |
CCA_MODE | --mode |
CCA_LICENSE | --license-key |
CCA_LICENSE_FILE | --license-file |
CCA_BUNDLE_PATH | --bundle-path |
Exit Codes
| Code | Meaning |
|---|---|
0 | Success |
| non-zero | An error occurred (invalid arguments, auth/permission failure, network error, or a hard doctor failure). Use --log-level debug for details. |
Next Steps
- Environment Variables — configure via env
- Configuration — flags, env, and stored credentials
- AWS Provider — AWS-specific options
- Azure Provider — Azure-specific options