# CLI Configuration

The Augint Billing CLI uses a hierarchical configuration system that allows flexible configuration across different environments and machines.

## Configuration Precedence

Configuration values are loaded in the following order (highest precedence first):

1. **Command-line arguments** - Directly passed to CLI commands
2. **Environment variables** - Set in your shell
3. **Local project config** - `./.env` file in current directory
4. **User global config** - `~/.augint/.env` file
5. **Default values** - Built-in defaults

Each level overrides values from lower-precedence sources.

## Environment-Specific Keys

The CLI supports three environments with automatic prefix handling:

- **Default** (no environment specified): Uses non-prefixed keys
- **Staging** (`--environment staging`): Looks for `STAGING_` prefixed keys first
- **Production** (`--environment production`): Looks for `PROD_` prefixed keys first

### Key Resolution Example

When running `ai-billing products setup staging`, the CLI looks for Stripe keys in this order:

1. `STAGING_STRIPE_SECRET_KEY` (environment-specific)
2. `STRIPE_SECRET_KEY` (fallback to non-prefixed)
3. `STRIPE_TEST_SECRET_KEY` (alternative test key)

## Configuration Files

### User Global Config: `~/.augint/.env`

Create this file to set defaults for all your projects:

```bash
# ~/.augint/.env
# Global defaults for all Augint projects

# Default Stripe keys
STRIPE_SECRET_KEY="sk_test_default_key"

# Staging environment
STAGING_STRIPE_SECRET_KEY="sk_test_staging_key"
STAGING_AWS_REGION="us-east-1"

# Production environment  
PROD_STRIPE_SECRET_KEY="sk_live_production_key"
PROD_AWS_REGION="us-west-2"

# AWS defaults
AWS_REGION="us-east-1"
AWS_ACCOUNT_ID="123456789012"
```

### Project Local Config: `./.env`

Create this file in your project directory to override global settings:

```bash
# ./.env
# Project-specific configuration

# Override staging Stripe key for this project
STAGING_STRIPE_SECRET_KEY="sk_test_project_specific_key"

# Project-specific AWS settings
STACK_NAME="my-billing-stack"
AWS_REGION="eu-west-1"
```

## Usage Examples

### Basic Usage

```bash
# Uses configuration from environment/files
ai-billing products setup staging

# Explicitly set via environment variable
STAGING_STRIPE_SECRET_KEY="sk_test_..." ai-billing products setup staging
```

### Working Across Projects

1. Set up global config once:
```bash
mkdir -p ~/.augint
cat > ~/.augint/.env << EOF
STAGING_STRIPE_SECRET_KEY="sk_test_global_key"
PROD_STRIPE_SECRET_KEY="sk_live_global_key"
EOF
```

2. Use CLI in any project:
```bash
cd ~/project1
ai-billing products setup staging  # Uses global key

cd ~/project2  
echo 'STAGING_STRIPE_SECRET_KEY="sk_test_project2_key"' > .env
ai-billing products setup staging  # Uses project-specific key
```

### Diagnostics

Check which configuration sources are being used:

```bash
ai-billing products diagnose
```

This shows:
- Which config files exist
- Which keys are found
- Where each key is loaded from

## Best Practices

1. **Security**: Never commit `.env` files with real keys to version control
2. **User Config**: Use `~/.augint/.env` for personal development keys
3. **Project Config**: Use `./.env` for project-specific settings
4. **CI/CD**: Set environment variables directly in your CI/CD pipeline
5. **Production**: Use `PROD_` prefixed keys and keep them separate from test keys

## Environment Variables Reference

### Core Configuration

| Variable | Description | Example |
|----------|-------------|---------|
| `STRIPE_SECRET_KEY` | Default Stripe API key | `sk_test_...` |
| `AWS_REGION` | AWS region | `us-east-1` |
| `AWS_ACCOUNT_ID` | AWS account ID | `123456789012` |
| `STACK_NAME` | CloudFormation stack name | `augint-billing` |

### Staging Environment

| Variable | Description | Example |
|----------|-------------|---------|
| `STAGING_STRIPE_SECRET_KEY` | Staging Stripe key | `sk_test_...` |
| `STAGING_API_USAGE_PRODUCT_ID` | Staging product ID | `prod_...` |
| `STAGING_BASE_SUBSCRIPTION_PRICE_ID` | Staging subscription price | `price_...` |
| `STAGING_METERED_USAGE_PRICE_ID` | Staging metered price | `price_...` |

### Production Environment

| Variable | Description | Example |
|----------|-------------|---------|
| `PROD_STRIPE_SECRET_KEY` | Production Stripe key | `sk_live_...` |
| `PROD_API_USAGE_PRODUCT_ID` | Production product ID | `prod_...` |
| `PROD_BASE_SUBSCRIPTION_PRICE_ID` | Production subscription price | `price_...` |
| `PROD_METERED_USAGE_PRICE_ID` | Production metered price | `price_...` |

## Migration from Old Configuration

If you're upgrading from an older version:

1. The CLI still reads environment variables directly
2. Old `.env` files continue to work
3. The new system adds more flexibility without breaking existing setups

Simply create `~/.augint/.env` for global defaults when convenient.
