Metadata-Version: 2.4
Name: costguard-cli
Version: 2.0.8
Summary: CostGuard CI/CD validation CLI — shift-left cost governance for cloud infrastructure
Author-email: SKYXOPS <engineering@skyxops.com>
License-Expression: LicenseRef-Proprietary
Keywords: costguard,cost,governance,finops,cloud,terraform,cloudformation,iac,ci-cd,budget,guardrails,skyxops
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: jinja2>=3.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install costguard-cli
```

## Quick Start

```bash
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.

```yaml
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.

```yaml
- 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`.

```yaml
- 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.
