← Back to Documentation

CLI Reference

StackSage is installed via pip and runs entirely on your machine. It has two commands:

CommandRequires license?Use case
stacksage scanNoSelf-serve: run locally or in CI. Free tier shows top 50 findings by savings.
stacksage auditYes (STACKSAGE_LICENSE)Licensed: all findings + remediation plan. Designed for CI/CD pipelines.

Installation

pip install stacksage

stacksage scan

Scans your AWS account, analyses waste, estimates savings, and opens an HTML report in your browser. No license required — free tier shows your top 50 findings ranked by estimated monthly savings. Security & posture checks are always shown in full.

stacksage scan [OPTIONS]

Options

OptionDefaultDescription
--profile TEXT—AWS named profile or SSO profile (e.g. my-sso-profile). Uses default credentials if omitted.
--role-arn TEXT—Assume this read-only IAM role ARN. Takes precedence over --profile.
--external-id TEXT—ExternalId to pass when assuming the role (optional).
--regions TEXTall enabledComma-separated AWS regions to scan, e.g. us-east-1,eu-west-1.
--out DIRECTORYreports/Directory to write report files into.
--use-cloudwatchoffEnable CloudWatch utilisation metrics for more accurate findings (recommended).
--use-cost-exploreroffInclude historical spend summary from Cost Explorer.
--check-taggingoffFlag resources missing required tags (opt-in to reduce noise).
--cw-days INTEGER14CloudWatch metrics lookback window in days.
--cw-max-queries INTEGER500Maximum CloudWatch API calls per run. Findings that hit the cap are flagged as skipped-budget.
--no-browseroffDo not auto-open the HTML report in a browser after the scan.
--demooffRun with synthetic data — no AWS calls or credentials needed.
--log-level TEXTINFOStructured JSON log verbosity: DEBUG, INFO, WARNING, ERROR.
--quietoffSuppress progress output.

Examples

Default credentials

stacksage scan

Named AWS profile or SSO

stacksage scan --profile my-sso-profile

Cross-account read-only role

stacksage scan --role-arn arn:aws:iam::123456789012:role/StackSageReadOnly

Recommended flags for a thorough scan

stacksage scan --use-cloudwatch --use-cost-explorer --check-tagging

Specific regions, no browser

stacksage scan --regions us-east-1,eu-west-1 --no-browser

Unlock all findings with a license

export STACKSAGE_LICENSE=your-license-key
stacksage scan

stacksage audit

Runs a full licensed audit. Requires a valid license key in the STACKSAGE_LICENSE environment variable. Unlocks all findings, the full remediation plan, and every report section. Designed for CI/CD pipelines and scheduled audits.

STACKSAGE_LICENSE=your-key stacksage audit [OPTIONS]

Options

OptionDefaultDescription
--profile TEXT—AWS named profile or SSO profile. Uses default credentials if omitted.
--role-arn TEXT—Assume this read-only IAM role ARN. Takes precedence over --profile.
--external-id TEXT—ExternalId to pass when assuming the role (optional).
--regions TEXTall enabledComma-separated AWS regions to scan.
--out DIRECTORYreports/Directory to write report files into.
--format [html|json]htmlOutput format. json prints the raw findings object.
--use-cloudwatchoffEnable CloudWatch utilisation metrics (recommended).
--use-cost-exploreroffInclude historical spend summary from Cost Explorer.
--liveoffConvenience flag: enables --use-cloudwatch, --use-cost-explorer, and --live-pricing in one flag.
--check-taggingoffFlag resources missing required tags (opt-in).
--cw-days INTEGER14CloudWatch metrics lookback window in days.
--cw-max-queries INTEGER500Maximum CloudWatch API calls per run.
--live-pricingoffUse the live AWS Pricing API for EC2 rates (default: static prices).
--demooffRun with synthetic data — useful for testing the pipeline.
--log-level TEXTINFODEBUG, INFO, WARNING, ERROR.
--quietoffSuppress progress output (errors only).

Examples

Basic licensed audit

export STACKSAGE_LICENSE=your-license-key
stacksage audit --profile my-sso-profile --use-cloudwatch --use-cost-explorer

Cross-account role in CI

STACKSAGE_LICENSE=$LICENSE stacksage audit \
  --role-arn arn:aws:iam::123456789012:role/StackSageReadOnly \
  --use-cloudwatch --use-cost-explorer \
  --out ./results

Full live mode (CloudWatch + Cost Explorer + live pricing)

STACKSAGE_LICENSE=$LICENSE stacksage audit --live --out ./results

GitHub Actions workflow snippet

- name: Run StackSage audit
  env:
    STACKSAGE_LICENSE: ${{ secrets.STACKSAGE_LICENSE }}
  run: |
    stacksage audit \
      --role-arn arn:aws:iam::123456789012:role/StackSageReadOnly \
      --use-cloudwatch --use-cost-explorer \
      --out ./results

- name: Upload report
  uses: actions/upload-artifact@v4
  with:
    name: stacksage-report-${{ github.run_number }}
    path: results/
    retention-days: 30

See the GitHub Actions setup guide for the full workflow including OIDC role assumption.

JSON output for downstream processing

STACKSAGE_LICENSE=$LICENSE stacksage audit --format json --out ./results

Environment variables

VariableDescription
STACKSAGE_LICENSELicense key. Required for stacksage audit. Also unlocks all findings in stacksage scan.
STACKSAGE_PRICING_MODESet to api to use the live AWS Pricing API for EC2 rates (default: static).
AWS_PROFILEStandard AWS profile env var — respected by StackSage.
AWS_DEFAULT_REGIONStandard AWS region env var — respected by StackSage.

Related topics