Commands

CloudOpt command reference.

CloudOpt is one binary with a short command set. Script output is JSON on stdout. Progress and errors go to stderr.

Workspace setup

Command Purpose
cloudopt init Create workspace directories and default configuration
cloudopt version Print version information

Workspace management

Back up the database, harden permissions, purge account data, or export diagnostics. Retention and audit settings: Configuration.

Command Purpose
cloudopt workspace secure-permissions Apply restrictive permissions (0750 dirs, 0600 files) on workspace paths
cloudopt workspace backup Copy the SQLite database to a backup file
cloudopt workspace restore Replace the workspace database from a backup
cloudopt workspace purge-account Delete all snapshots and account metadata for one account ID
cloudopt workspace export-diagnostics Export anonymized local diagnostics JSON (telemetry off by default)
cloudopt workspace export-archive Export engagement reports as a zip without credentials

Workspace flags

Flag Commands Description
--output backup, export-diagnostics, export-archive Output path (defaults under data/backups/, tmp/, or reports/)
--from restore Absolute path to backup file (required)
--account-id purge-account Canonical account ID to purge (required)
--verify purge-account Verify no snapshots remain after purge

Data collection

AWS

Command Purpose
cloudopt collect aws inventory Snapshot EC2, EBS, VPC, RDS inventory
cloudopt collect aws cost Collect and attribute billing data
cloudopt collect aws metrics Collect CloudWatch utilization metrics

GCP

Command Purpose
cloudopt collect gcp inventory Snapshot Compute Engine, Cloud SQL, VPC, GKE inventory
cloudopt collect gcp cost Collect billing from BigQuery export and attribute to resources
cloudopt collect gcp metrics Collect Cloud Monitoring utilization metrics

Other

Command Purpose
cloudopt import-fixture Load sample YAML data for offline use
cloudopt capabilities matrix Print the cross-provider capability matrix

--dry-run checks access without collecting. --offline uses bundled sample data instead of live APIs.

Common flags

Flag Description
--workspace-dir Path to your CloudOpt workspace (default: ~/.cloudopt)
--regions Comma-separated regions to scan (inventory)
--projects Comma-separated GCP project IDs to scan (GCP inventory)
--lookback-days Billing or metrics lookback window
--snapshot-id Attach cost or metrics to a specific inventory snapshot
--role-arn Assume an IAM role for cross-account access (AWS)
--impersonate-service-account Impersonate a GCP service account

Analysis and reporting

Command Purpose
cloudopt analyze Run optimization checks on collected data
cloudopt report Generate an HTML or JSON report
cloudopt cost-reconcile Compare collected costs against billing totals

Analyze flags

Flag Description
--snapshot-id Analyze a specific snapshot (default: latest complete)
--rules Run only specific checks (comma-separated rule IDs)
--category Run only checks in specific categories (compute, storage, etc.)

Report flags

Flag Description
--format html|json Output format (default: html)
--output Custom output file path
--redact Replace account and resource IDs with aliases
--analysis-run-id Report from a specific analysis run

Terraform correlation

Link inventory to Terraform state/plan JSON. CloudOpt does not run the Terraform CLI. Details: Terraform correlation.

Command Purpose
cloudopt terraform correlate Link live resources to Terraform addresses; optional plan forecast and finding enrichment

Terraform correlate flags

Flag Description
--state-json Path to terraform show -json state output (required)
--plan-json Path to terraform show -json plan output (optional forecast)
--mappings YAML file with explicit resource_id → terraform_address mappings
--snapshot-id Snapshot for inventory correlation (default: latest complete)
--analysis-run-id Analysis run for finding enrichment
--enrich-findings Attach IaC context to analysis findings
--json-out Write full correlation JSON to path
--markdown-out Write PR-comment Markdown summary to path
--json Emit correlation JSON on stdout
--strict-plan Exit non-zero when plan policy warnings are present

Typical workflow

cloudopt init --workspace-dir "$HOME/.cloudopt"

cloudopt collect aws inventory --regions us-east-1,us-west-2
cloudopt collect aws cost --lookback-days 30
cloudopt collect aws metrics --lookback-days 14

cloudopt analyze
cloudopt report --format html --redact

# Optional: map findings to Terraform (requires state JSON from your pipeline)
cloudopt terraform correlate --state-json ./state.json --enrich-findings

For GCP, swap collect aws for collect gcp and add project or billing export flags. See the GCP guide.

Before upgrading CloudOpt, back up the workspace database:

cloudopt workspace backup --output "$HOME/.cloudopt/data/backups/pre-upgrade.db"

Help

cloudopt --help
cloudopt collect aws inventory --help
cloudopt collect gcp inventory --help
cloudopt analyze --help
cloudopt report --help
cloudopt capabilities matrix --help
cloudopt terraform correlate --help
cloudopt workspace backup --help

Exit codes

Code Meaning
0 Success
1 General error
2 Invalid input or configuration
3 Collection failed
4 Analysis failed
5 Partial success (e.g. Terraform correlation with ambiguous matches)
7 Terraform plan policy warnings under --strict-plan

Ctrl+C stops the command. Snapshots and analysis runs stay on disk. Interrupted collects leave in-progress rows; CloudOpt deletes those after incomplete_snapshot_ttl_hours (default 24).