Synopsis
cloudburn discover [flags]
cloudburn discover <subcommand> [flags]
Description
Queries live AWS resources via AWS Resource Explorer, enriches them with service-specific data via hydrators, and evaluates cost optimization rules against the results.
Resource Explorer must be set up before running discovery with catalog-backed rules, which includes the AWS Core preset. Use cloudburn discover init to create the required indexes. A run whose enabled rules only read account-scoped datasets, such as the Cost Optimization Hub rules, skips the Resource Explorer catalog.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--config | string | auto-discovery | Path to a .cloudburn.yml config file. Required to apply config in CI — see CI environments. |
--enabled-rules | string | AWS Core preset | Comma-separated rule IDs to include. Replaces the AWS Core preset; also the way to activate the opt-in rules. |
--disabled-rules | string | none | Comma-separated rule IDs to exclude from the selected set — the AWS Core preset, or your enabled-rules list when one is set. |
--service | string | all services | Comma-separated services to scan (e.g. ec2,ebs). |
--region | string | current region | AWS region to discover. Defaults to the current AWS region from AWS_REGION. |
--timeout | number | 300 | Total discovery deadline in seconds. Whole number from 1 to 2147483. See Discovery timeout. |
--cache | string | normal | Evidence cache mode: normal, refresh, or off. See Evidence cache. |
--cache-dir | string | see below | Directory holding the local evidence cache. |
--cache-context | string | session scope | Effective authorization and session-policy revision used to decide whether cached evidence may be reused. |
--exit-code | boolean | false | Exit with code 1 when any active finding exists. |
--fail-on | string | none | Exit with code 1 when an active finding meets or exceeds this severity: high, medium, or low. Can also be set as discovery.fail-on in config. |
The CLI targets one region per run. Multi-region discovery stays available through the SDK and still needs a Resource Explorer aggregator plus an unfiltered default view in the aggregator region.
Opt-in rules
Some built-in rules sit outside the AWS Core preset because they need AWS setup CloudBurn will not perform for you. Activate them per run with --enabled-rules, or per project in discovery.enabled-rules. See Enabling and Disabling Rules for the list and why each rule is excluded.
cloudburn discover --enabled-rules CLDBRN-AWS-COSTOPTIMIZATIONHUB-3
cloudburn discover --enabled-rules CLDBRN-AWS-LAMBDA-4
--enabled-rules replaces the preset, so a run that lists only opt-in rules checks only those rules. List the other rule IDs you still want, or use a config file when the selection gets long.
Discovery timeout
A discovery run has a total deadline of five minutes. --timeout <seconds> changes it:
cloudburn discover --timeout 600
The value must be a whole number of seconds between 1 and 2147483. When the deadline expires, CloudBurn stops the remaining AWS work and exits with code 2 reporting the timeout. SDK callers set the same deadline with timeoutMs and can pass their own AbortSignal.
Evidence cache
Discovery reuses fresh, complete evidence it collected on an earlier run instead of calling AWS again. Rules and configuration are evaluated on every run, so a cached run still reflects your current rule selection.
| Flag | Behavior |
|---|---|
--cache normal | Default. Reuse fresh, complete evidence and collect what is missing or expired. |
--cache refresh | Collect current evidence and never fall back to cached evidence when collection fails. Only complete, successful loads replace stored entries. |
--cache off | Bypass persistent reads and writes, including public pricing. |
--cache-dir <path> | Directory for the evidence store. Defaults to $XDG_CACHE_HOME/cloudburn/evidence, or ~/.cache/cloudburn/evidence when XDG_CACHE_HOME is unset. |
--cache-context <id> | Identifies the effective authorization and session-policy revision. Change it when those permissions change. |
cloudburn discover --cache refresh
cloudburn discover --cache off
cloudburn discover --cache-dir /path/to/evidence --cache-context policy-revision-2
Reusing customer evidence requires a safe scope. Temporary AWS credentials supply one through their session; long-term credentials do not, so pass --cache-context to identify the permissions the evidence was collected under. An account ID or role ARN alone is not enough. Without either, customer evidence reuse stays off and only public pricing is reused. Cache entries never contain credentials.
A cache hit is not proof of AWS coverage. Source delays and unknown resources stay visible through evidence completeness, coverage, and diagnostics. Table output ends with a freshness summary, and --format json keeps the full evidence array. See Evidence freshness.
Progress output
While discovery runs, CloudBurn streams progress to stderr when stderr is attached to an interactive terminal: catalog ready, datasets completed, and one line per rule as it finishes with its ID, status, and finding count.
discover: catalog ready with 412 resources from eu-central-1
discover: datasets 7/18 loaded (aws-ec2-instances)
discover: rules 12/78 (CLDBRN-AWS-EBS-1: triggered, findings: 3, provisional)
A rule line reports triggered, passed, not_applicable, or unknown. These lines are provisional: they describe the work finished so far, and the final report plus the exit code are authoritative. Progress is silent for piped or scripted runs, --debug tracing takes priority over progress lines when both would apply, and --format json still writes one final result to stdout.
Subcommands
| Subcommand | Description |
|---|---|
init | Set up AWS Resource Explorer indexes in your account |
status | Show the current Resource Explorer status |
supported-resource-types | List resource types CloudBurn can discover |
init
Synopsis
cloudburn discover init [flags]
Description
Attempts to set up AWS Resource Explorer indexes across enabled regions and configure an aggregator in the selected region. Without --region, it reuses an existing aggregator or selects the current active region from your AWS profile or AWS_REGION. An existing aggregator is reused even when regional coverage is incomplete. Access restrictions can leave a local setup instead of an aggregator; inspect coverage, indexType, and the warning before relying on cross-region discovery.
See the Resource Explorer Setup guide for a detailed walkthrough.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--region | string | current region | Region to use as the aggregator |
Example
cloudburn discover init
cloudburn discover init --region eu-west-1
status
Synopsis
cloudburn discover status
Description
Displays the current state of Resource Explorer in your account, including which regions are indexed and whether an aggregator is configured.
Output format
Table output prints an account summary, then one row per enabled region:
+-----------------------+-----------+
| Field | Value |
+-----------------------+-----------+
| accessibleRegionCount | 17 |
| aggregatorRegion | eu-west-1 |
| coverage | full |
| indexedRegionCount | 17 |
| totalRegionCount | 17 |
+-----------------------+-----------+
+--------------+---------------------+---------+------------+
| Region | IndexType | Status | ViewStatus |
+--------------+---------------------+---------+------------+
| eu-west-1 | aggregator (active) | indexed | present |
| eu-central-1 | local | indexed | present |
+--------------+---------------------+---------+------------+
Columns with no data for any region are dropped, so a Notes column appears only when CloudBurn has something to report about a region.
| Field | Values |
|---|---|
coverage | full, partial, local_only, none |
Status | indexed, not_indexed, access_denied, error, unsupported |
ViewStatus | present, missing, filtered, access_denied, error, unknown |
accessibleRegionCount | Regions CloudBurn could query, out of totalRegionCount |
A warning field is added to the summary when Resource Explorer setup is incomplete. --format json returns the same data as { "summary": ..., "regions": [...] }.
Example
cloudburn discover status
cloudburn --format json discover status
supported-resource-types
Synopsis
cloudburn discover supported-resource-types
Description
Lists all AWS resource types supported by Resource Explorer. This is the indexing catalog, not a list of resource types with CloudBurn rules; use cloudburn rules list to check rule coverage. Output has two columns, ResourceType and Service; a resource type CloudBurn cannot map to a service is reported as unknown.
Example
cloudburn discover supported-resource-types
Exit codes
cloudburn discover exits 0 when no finding trips a gate, 1 when an active finding satisfies --exit-code or --fail-on, and 2 on runtime or usage errors such as missing credentials, a Resource Explorer that is not set up, or an expired --timeout deadline. The Exit codes guide has the full contract.
Examples
Run discovery in the current region:
cloudburn discover
Scan a specific region with JSON output:
cloudburn --format json discover --region us-west-2
Filter to EC2 and EBS rules only:
cloudburn discover --service ec2,ebs
Enable the opt-in account-wide tagging rule and fail CI when it finds untagged resources. --enabled-rules replaces the preset, so the selected set contains only this low-severity rule — the gate must be low to ever trip:
cloudburn discover --enabled-rules CLDBRN-AWS-TAGGING-1 --fail-on low
Force a fresh collection and give the run ten minutes:
cloudburn discover --cache refresh --timeout 600
What's next
| Quickstart: Discover AWS Resources | Step-by-step first discovery scan |
| Exit Codes | Use exit codes in CI/CD pipelines |
| Rules | Rules evaluated during discovery |