Metadata-Version: 2.4
Name: costguard-cli
Version: 2.0.0
Summary: CostGuard CI/CD validation CLI — shift-left cost governance for cloud infrastructure
Author-email: SKYXOPS <engineering@skyxops.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://skyxops.com/costguard
Project-URL: Documentation, https://docs.skyxops.com/costguard-cli
Project-URL: Repository, https://dev.azure.com/skyxops/basecamp/_git/costguard-cli
Project-URL: Changelog, https://dev.azure.com/skyxops/basecamp/_git/costguard-cli?path=/CHANGELOG.md
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 plan against cost policies, budget limits, and guardrails — before infrastructure is deployed.

## Install

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

## Usage

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

# Post results as PR/MR comment (auto-detects GitLab/GitHub/Azure DevOps)
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

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

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

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