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