costguard-cli 2.0.9

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.

Install

pip install costguard-cli

Quick Start

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_API_URL	API endpoint (default: https://api.skyxops.com)	No
COSTGUARD_BUDGET_CODE	Budget code for validation (use --skip-budget for pricing-only)	No

CI/CD Integration

GitLab CI

Required CI/CD variables:

Variable	How to set	Purpose
COSTGUARD_API_KEY	Settings → CI/CD → Variables (masked)	API auth
GITLAB_TOKEN	Project/Group Access Token with api scope	Post MR comments

Note: CI_JOB_TOKEN cannot post MR comments — GitLab restricts it to read-only. Create a Project Access Token (Settings → Access Tokens → api scope) or a Group Access Token for all projects in the group.

stages:
  - cost-review

costguard-review:
  stage: cost-review
  image: python:3.12-slim
  script:
    - pip install --quiet costguard-cli
    - costguard-validate --plan plan.json --post-comment
  allow_failure:
    exit_codes:
      - 2
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

GitHub Actions

Required secrets: COSTGUARD_API_KEY. GITHUB_TOKEN is auto-provided.

- name: CostGuard Validation
  env:
    COSTGUARD_API_KEY: ${{ secrets.COSTGUARD_API_KEY }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    pip install -q costguard-cli
    costguard-validate --plan plan.json --post-comment

Azure DevOps

Required variables: COSTGUARD_API_KEY, SYSTEM_ACCESSTOKEN.

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

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

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.