Metadata-Version: 2.4
Name: cz-billing-generator
Version: 3.1.1
Summary: CLI tool for generating and uploading synthetic billing data to CloudZero
Author-email: CloudZero <support@cloudzero.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/cloudzero/czbillgen
Keywords: CloudZero,czbg,billing,generator,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: polars>=0.20.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=14.0.0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyarrow>=19.0.1
Provides-Extra: full
Requires-Dist: numpy>=1.24.0; extra == "full"
Requires-Dist: boto3>=1.26.0; extra == "full"
Requires-Dist: psutil>=6.1.0; extra == "full"
Requires-Dist: tenacity>=9.0.0; extra == "full"
Requires-Dist: python-dateutil>=2.8.0; extra == "full"
Requires-Dist: requests>=2.32.0; extra == "full"

# CloudZero Billing Generator (CZBG)

Generate and upload synthetic cloud billing data to CloudZero organizations. Built for CloudZero sales engineers and demo teams.

## Quick Start

```bash
# 1. Install
uv tool install cz-billing-generator

# 2. Set up credentials (see Getting Started)
# Edit ~/.czbg/.env with credentials from 1Password (Demo vault)

# 3. Download configs
czbg config download

# 4. Run your first job via API
czbg generate run --config czbg-configs/generate/production/standard/aws/base/ec2.aws.yaml

# 5. Time-shift data to different months
czbg upload time-shift --config czbg-configs/upload/time-shift/production-2025-to-2026.yaml
```

**New to CZBG?** → [Getting Started Guide](docs/GETTING_STARTED.md)

## What is CZBG?

CZBG generates realistic synthetic cloud billing data for CloudZero demos and testing:

- **Multi-Cloud**: AWS, Azure, GCP, and 10+ SaaS providers
- **Realistic Data**: Behavioral variance, anomalies, seasonal patterns
- **API-First**: Serverless execution via Lambda + ECS (v2.0+)
- **Full Pipeline**: Generate → Upload (K8s, usage, discount, and metadata features are automatically applied during generation)

**Default execution is now via API** - jobs run on serverless infrastructure, not your local machine. Use `--local` flag for local debugging.

## Installation

**Prerequisites:**
- Python 3.10+
- AWS SSO access (cz-test-env-1)
- CloudZero API credentials

**Install:**
```bash
uv tool install cz-billing-generator
```

**Upgrade to latest:**
```bash
uv tool upgrade cz-billing-generator
```

## Core Workflows

### Generate Billing Data

```bash
# Generate base AWS billing data (via API)
czbg generate run --config czbg-configs/generate/production/standard/aws/base/ec2.aws.yaml

# Generate locally for debugging
czbg generate run --config czbg-configs/generate/production/standard/aws/base/ec2.aws.yaml --local
```

**Note**: K8s, usage, discount, and metadata features are automatically applied during generation when enabled in config. No separate commands needed.

### Upload to CloudZero

```bash
# Upload generated data to organizations
czbg upload generated --config czbg-configs/upload/production/production.upload.yaml

# Time-shift data to different months (bulk operation)
czbg upload time-shift --config czbg-configs/upload/time-shift/production-2025-to-2026.yaml
```

### Manage Connections & Data

**Connection Management:**
```bash
# List connections for an organization
czbg connection list DemoOrg

# Show detailed connection info
czbg connection show DemoOrg aws-connection-1

# Create a new connection
czbg connection create DemoOrg AWS

# Delete a connection
czbg connection delete DemoOrg aws-connection-1
```

**Drop Management (S3 Data):**
```bash
# List billing periods and drops
czbg drop list DemoOrg AWS
czbg drop list DemoOrg AWS --period 20250301-20250401

# Set active drop (switch versions)
czbg drop set-active DemoOrg AWS 20250301-20250401 20250916T190931Z

# Rollback to previous drop
czbg drop rollback DemoOrg AWS 20250301-20250401

# Delete inactive drops
czbg drop delete DemoOrg AWS 20250301-20250401 20250916T182148Z

# Find orphaned data
czbg drop orphaned --org DemoOrg

# Bulk cleanup
czbg drop delete-provider DemoOrg AWS
czbg drop delete-org DemoOrg
```

**See also:** [Migration Guide](docs/migration/connection-commands-migration.md) for workflow patterns.

### Monitor Jobs

```bash
# List all jobs
czbg jobs list

# Check job status
czbg jobs describe <job-id>
```

## Configuration Management

```bash
# Download all configs from S3
czbg config download

# Download specific stage configs
czbg config download --prefix czbillgen/configs/generate/

# List available configs in S3
czbg config list
```

## Documentation

### By User Type

**👤 New Users** → [Getting Started](docs/GETTING_STARTED.md)
*Step-by-step setup and first workflows*

**📊 Sales Engineers** → [API Workflows](docs/user-guides/api-workflows.md)
*Common demo scenarios and API execution*

**🔧 Config Writers** → [Generate Config Guide](docs/reference/generate-config-writing-guide.md)
*Creating custom billing scenarios*

**💻 Developers** → [Development Guide](docs/development/README.md)
*Contributing and architecture*

### Quick References

- [Command Reference](docs/reference/commands.md) - All CLI commands
- [Configuration Reference](docs/reference/configuration.md) - YAML config formats
- [Troubleshooting](docs/reference/troubleshooting.md) - Common issues
- [Complete Documentation](docs/README.md) - Full documentation hub

## Key Features

### v2.0 - API-First Architecture

**Breaking Change:** All commands now execute via API by default (Lambda + ECS workers).

- ✅ **Serverless execution** - No local processing required
- ✅ **Auto-scaling** - Workers scale based on job queue
- ✅ **Job tracking** - Monitor progress via DynamoDB
- ✅ **Works anywhere** - Run from any machine with CLI access

Use `--local` flag to opt-in to local execution for development/debugging.

### Multi-Stage Pipeline

```
Generate → K8s → Metadata → Usage → Discount → Upload
```

Each stage enriches billing data:
- **Generate**: Base cloud billing costs
- **K8s**: Kubernetes allocation and workload mapping
- **Metadata**: Tags, regions, resource IDs
- **Usage**: Usage metrics with realistic rates
- **Discount**: Cloud savings plans and discounts
- **Upload**: Stream to CloudZero organizations

### Time-Shift Capability

Move generated data to different time periods:
- Copy Nov 2025 data → Nov 2026
- Preserves all metadata, K8s allocations, and anomalies
- Parallel processing by provider (AWS, Azure, GCP)

## Support

**📚 Documentation**: [Complete docs](docs/README.md)
**💬 Internal**: CloudZero Slack #demo-environment
**🐛 Issues**: [GitHub Issues](https://github.com/cloudzero/cz-billing-generator/issues)

## Quick Help

```bash
# Get help for any command
czbg --help
czbg generate --help
czbg upload --help

# Check version
czbg jobs list  # Version shown in output
```

---

**Current Version:** 2.0.0
**License:** Proprietary - CloudZero Internal Use Only
**Maintainer:** CloudZero Demo Engineering Team
