Metadata-Version: 2.4
Name: cost-guardrails
Version: 2.7.1
Summary: Cost Guardrails CI/CD validation CLI — shift-left cost governance for cloud infrastructure
Author-email: SKYXOPS <engineering@skyxops.com>
License-Expression: LicenseRef-Proprietary
Keywords: cost-guardrails,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
Requires-Dist: pyyaml>=6.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

# Cost Guardrails 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

```bash
pip install cost-guardrails
```

## Quick Start

```bash
# Set your API key
export COST_GUARDRAILS_API_KEY="your-api-key"

# Validate costs
cost-guardrails --plan plan.json --budget-code CS-FY2026-BU105-M03 --post-comment
```

## Configuration

| Env Variable | Description | Required |
|-------------|-------------|:---:|
| `COST_GUARDRAILS_API_KEY` | API authentication key | Yes |
| `COST_GUARDRAILS_BUDGET_CODE` | Budget code for validation (use `--skip-budget` for pricing-only) | No |
| `COST_GUARDRAILS_TAG` | Tag to identify this comment (e.g. production, staging) | No |

> API URL is built-in. Set `COST_GUARDRAILS_API_URL` only for custom deployments.

## CI/CD Integration

### Azure DevOps (Extension)

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

```yaml
- task: Cost Guardrails@1
  inputs:
    planPath: plan.json
    budgetCode: $(COST_GUARDRAILS_BUDGET_CODE)
  env:
    COST_GUARDRAILS_API_KEY: $(COST_GUARDRAILS_API_KEY)
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)
```

[Full Azure DevOps Guide](docs/integrations/azure-devops.md)

### GitHub Actions

```yaml
- uses: skyxops-io/costguard-action@v1
  with:
    plan-path: plan.json
    api-key: ${{ secrets.COST_GUARDRAILS_API_KEY }}
    budget-code: ${{ secrets.COST_GUARDRAILS_BUDGET_CODE }}
```

[Full GitHub Actions Guide](docs/integrations/github-actions.md)

### GitLab CI

```yaml
include:
  - remote: 'https://gitlab.com/skyxops-io/cost-guardrails-templates/-/raw/v1/gitlab/cost-guardrails.yml'

cost-guardrails:
  extends: .cost-guardrails-review
  needs: [terraform-plan]
```

[Full GitLab CI Guide](docs/integrations/gitlab-ci.md)

### Any CI/CD Platform

```yaml
- script: |
    pip install -q cost-guardrails
    cost-guardrails --plan plan.json --post-comment
  env:
    COST_GUARDRAILS_API_KEY: $(COST_GUARDRAILS_API_KEY)
```

[Generic CI/CD Guide](docs/integrations/generic-ci.md)

## 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:

```bash
cost-guardrails --plan prod/plan.json --tag production --post-comment
cost-guardrails --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: `COST_GUARDRAILS_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 Cost Guardrails 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](docs/getting-started.md) | Prerequisites, installation, quick start |
| [CLI Reference](docs/cli-reference.md) | Complete flag and option reference |
| [Architecture](docs/architecture.md) | Technical architecture, API flow, data model |
| [Troubleshooting](docs/troubleshooting.md) | Common issues across all platforms |

### Integration Guides

| Platform | Guide |
|----------|-------|
| [Azure DevOps](docs/integrations/azure-devops.md) | Native extension (`Cost Guardrails@1` task) |
| [GitHub Actions](docs/integrations/github-actions.md) | Composite action (`costguard-action@v1`) |
| [GitLab CI](docs/integrations/gitlab-ci.md) | Remote template (`include: remote:`) |
| [Generic CI/CD](docs/integrations/generic-ci.md) | Raw CLI for any platform |
