costguard-cli 2.0.3

CostGuard CI/CD validation CLI — shift-left cost governance for cloud infrastructure

CostGuard CLI

Shift-left cost governance for CI/CD pipelines. One command validates your Terraform plan against cost policies, budget limits, and guardrails — before infrastructure is deployed.

Install

pip install costguard-cli

Usage

# Validate a Terraform plan
costguard-validate --plan plan.json --format terminal

# Post results as PR/MR comment (auto-detects GitLab/GitHub/Azure DevOps)
# Idempotent: creates on first run, updates on re-push (never duplicates)
costguard-validate --plan plan.json --format markdown --post-comment

# Use cached result across pipeline stages
costguard-validate --cached costguard-result.json --format html --output-file report.html

Configuration

Option	Env Variable	Description
--api-url	COSTGUARD_API_URL	CostGuard API endpoint
--api-key	COSTGUARD_API_KEY	API authentication key
--budget-code	COSTGUARD_BUDGET_CODE	Budget code to validate against (e.g. CS-FY2026-M01)

Output Formats

Format	Use Case
terminal	Local development, CI logs
markdown	PR/MR comments
html	Executive reports, artifacts
json	Machine-readable, integrations

Exit Codes

Code	Decision	Meaning
0	ALLOW	Deployment permitted
1	BLOCK	Deployment blocked by guardrails
2	WARN	Deployment allowed with warnings
3	ERROR	Validation could not complete

CI/CD Integration

GitLab CI

costguard:
  script:
    - pip install costguard-cli
    - terraform show -json plan.tfplan > plan.json
    - costguard-validate --plan plan.json --format terminal --post-comment
  variables:
    COSTGUARD_API_URL: $COSTGUARD_API_URL
    COSTGUARD_API_KEY: $COSTGUARD_API_KEY

GitHub Actions

- name: CostGuard Validation
  env:
    COSTGUARD_API_URL: ${{ secrets.COSTGUARD_API_URL }}
    COSTGUARD_API_KEY: ${{ secrets.COSTGUARD_API_KEY }}
  run: |
    pip install costguard-cli
    terraform show -json plan.tfplan > plan.json
    costguard-validate --plan plan.json --format terminal --post-comment

Azure DevOps

- script: |
    pip install costguard-cli
    terraform show -json plan.tfplan > plan.json
    costguard-validate --plan plan.json --format terminal --post-comment
  env:
    COSTGUARD_API_URL: $(COSTGUARD_API_URL)
    COSTGUARD_API_KEY: $(COSTGUARD_API_KEY)

How It Works

1. Reads plan.json (output of terraform show -json)
2. Sends it to the CostGuard API
3. Receives cost breakdown, policy violations, budget status, and AI recommendations
4. Formats and displays results
5. Exits with appropriate code so the pipeline can ALLOW, WARN, or BLOCK

No cloud credentials required — the CLI only reads the plan file. All resource details are already in the Terraform plan output.