costguard-cli 2.4.0

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 or CloudFormation plan against cost policies, budget limits, and guardrails — before infrastructure is deployed.

Note: A SKYXOPS subscription is required to use this CLI. This module can run as a standalone tool or be integrated into CI/CD pipelines.

Install

pip install costguard-cli

Quick Start

# Set your API key
export COSTGUARD_API_KEY="your-api-key"

# Validate costs
costguard-validate --plan plan.json --budget-code CS-FY2026-BU105-M03 --post-comment

Configuration

Env Variable	Description	Required
COSTGUARD_API_KEY	API authentication key	Yes
COSTGUARD_BUDGET_CODE	Budget code for validation (use --skip-budget for pricing-only)	No
COSTGUARD_TAG	Tag to identify this comment (e.g. production, staging)	No

API URL is built-in. Set COSTGUARD_API_URL only for custom deployments.

CI/CD Integration

Azure DevOps (Extension)

Install the CostGuard extension from the VS Marketplace, then use the native task:

- task: CostGuard@1
  inputs:
    planPath: plan.json
    budgetCode: $(COSTGUARD_BUDGET_CODE)
  env:
    COSTGUARD_API_KEY: $(COSTGUARD_API_KEY)
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

Full Azure DevOps Guide

GitHub Actions

- uses: skyxops-io/costguard-action@v1
  with:
    plan-path: plan.json
    api-key: ${{ secrets.COSTGUARD_API_KEY }}
    budget-code: ${{ secrets.COSTGUARD_BUDGET_CODE }}

Full GitHub Actions Guide

GitLab CI

include:
  - remote: 'https://gitlab.com/skyxops-io/costguard-templates/-/raw/v1/gitlab/costguard.yml'

costguard:
  extends: .costguard-review
  needs: [terraform-plan]

Full GitLab CI Guide

Any CI/CD Platform

- script: |
    pip install -q costguard-cli
    costguard-validate --plan plan.json --post-comment
  env:
    COSTGUARD_API_KEY: $(COSTGUARD_API_KEY)

Generic CI/CD Guide

Output Formats

Format	Flag	Use Case
Terminal	--format terminal	CI logs (default)
Markdown	--format markdown	PR/MR comments
HTML	--format html	Executive reports
JSON	--format json	Integrations

Exit Codes

Code	Decision	Pipeline Effect
0	ALLOW	Continues
1	BLOCK	Stops
2	WARN	Continues (use allow_failure: exit_codes: [2])
3	ERROR	Stops

Multi-Environment Tags

Use --tag to post separate comments for each Terraform root or environment in a single MR/PR:

costguard-validate --plan prod/plan.json --tag production --post-comment
costguard-validate --plan staging/plan.json --tag staging --post-comment

Each tag gets its own isolated comment. Without --tag, a single comment is posted. Set via env var: COSTGUARD_TAG.

Comment Behavior

--post-comment is idempotent: creates one comment on first run, updates it on re-push. No duplicates. Works on GitLab MRs, GitHub PRs, and Azure DevOps PRs.

How It Works

1. Reads plan file (Terraform plan.json or CloudFormation changeset)
2. Sends to CostGuard API for pricing, budget validation, and guardrail checks
3. Displays cost breakdown, AI recommendations, and decision
4. Posts result as MR/PR comment (if --post-comment)
5. Exits with decision code so the pipeline can ALLOW, WARN, or BLOCK

No cloud credentials required — the CLI only reads the plan file.

Documentation

Doc	Description
Getting Started	Prerequisites, installation, quick start
CLI Reference	Complete flag and option reference
Architecture	Technical architecture, API flow, data model
Troubleshooting	Common issues across all platforms

Integration Guides

Platform	Guide
Azure DevOps	Native extension (CostGuard@1 task)
GitHub Actions	Composite action (costguard-action@v1)
GitLab CI	Remote template (include: remote:)
Generic CI/CD	Raw CLI for any platform