augint-org 0.6.1

CLI tool for managing AWS Organization accounts with Control Tower

augint-org (ai-org) 🚀

One-command AWS account provisioning with Control Tower integration and enterprise-grade automation.

Create production-ready AWS accounts in seconds. They auto-configure based on their environment. No manual setup required.

📊 Project Health

📖 Documentation	🧪 Tests	📊 Coverage	🔒 Security	⚖️ Compliance

✨ What Does It Do?

The ai-org CLI tool automates AWS multi-account management:

• Creates accounts with one command
• Auto-provisions resources based on environment (prod/staging/sandbox)
• Sets up CI/CD with GitHub Actions OIDC (no AWS keys!)
• Configures monitoring, backups, and compliance automatically
• Sends email notifications with ready-to-use configurations

🚀 Quick Start (5 minutes)

1. Install the CLI

# Install with pip (or pipx for isolation)
pip install augint-org

# Or with uv (recommended - 10-100x faster)
uv pip install augint-org

2. Configure Your Environment (Optional)

# Set your AWS profile (required)
export AWS_PROFILE=org

# Optional: Create personal defaults config
ai-org config init

# Or create manually at ~/.ai-org.env
cat > ~/.ai-org.env << EOF
AWS_PROFILE=org
DEFAULT_SSO_EMAIL=[e-mail]
DEFAULT_PERMISSION_SET=AWSAdministratorAccess
NOTIFICATIONS_EMAIL=[e-mail]
BUDGETS_MONTHLY_DEFAULT=1000
BUDGETS_ANOMALY_THRESHOLD=100
EOF

# Note: Environment variables override config file

3. Bootstrap Your Landing Zone

# One-time setup: Create OUs, deploy StackSets, configure policies
ai-org bootstrap

# This runs in minutes and sets up:
# ✅ OU structure (Workloads, Sandbox)
# ✅ 3 core StackSets with auto-deployment
# ✅ Service Control Policies for Workloads
# ✅ GitHub Actions authentication
# ✅ Cost management and budgets

4. Create Your First Project

# Create both staging and production accounts for a project
ai-org account create myapp

# What happens automatically:
# 1. Creates myapp-staging account → Workloads/Staging OU
# 2. Creates myapp-prod account → Workloads/Production OU
# 3. Waits for Control Tower provisioning
# 4. StackSets auto-deploy appropriate resources
# 5. Emails you ready-to-use .env configurations
# 6. Sets up AWS CLI profiles automatically

5. Deploy Your Application

# Your accounts are ready! Deploy with SAM or CDK
cd your-app/
sam deploy --profile myapp-staging

# Or use GitHub Actions (already configured!)
git push origin staging

📋 What Gets Deployed Where

Resource	Production	Staging	Sandbox
S3 Deployment Bucket	✅	✅	❌
GitHub OIDC + Roles	✅	✅	❌
CloudWatch Monitoring	✅	✅	❌
Cost Alerts	✅	✅	❌
Automated Backups	✅	❌	❌
Centralized Logging	✅	❌	❌
Security Policies	✅	✅	❌

🎯 Common Commands

# Account Management
ai-org account create <project>           # Create staging + prod accounts
ai-org account create <project> --prod    # Create only production
ai-org account list                       # List all accounts
ai-org account info <project>             # Show account details

# Infrastructure Management
ai-org status                              # Show landing zone health
ai-org stackset list                       # List deployed StackSets
ai-org stackset update <name>              # Update a StackSet
ai-org validate                            # Validate all configurations

# Configuration
ai-org config show                         # Display current config
ai-org config set notifications.email x@y  # Update config value
ai-org config profiles add <name>          # Add AWS CLI profile

# Development
ai-org account sandbox <name>              # Create sandbox account
ai-org costs report --days 30              # Cost analysis
ai-org compliance check                    # Compliance report

Billing Integration (Stripe)

The billing system automatically passes through AWS account costs to your customers via Stripe.

Initial Setup

1. Set your Stripe API keys in .env:

# For testing (uses Stripe test mode)
TEST_STRIPE_SECRET_KEY=sk_test_xxx

# For production (when ready)
STRIPE_SECRET_KEY=sk_live_xxx

2. Deploy the billing infrastructure:

make deploy  # Deploys billing stack along with other infrastructure

3. Create Stripe products (one-time):

ai-org billing setup

4. Enable Stripe EventBridge Integration (Manual - Required):
   • Go to Stripe Dashboard -> Developers -> Events
   • Click Add endpoint -> Select AWS EventBridge
   • Enter your AWS Account ID (shown after ai-org billing setup)
   • Select region: us-east-1
   • Select events to send (minimum required):
     • invoice.created
     • invoice.finalized
     • invoice.payment_succeeded
     • invoice.payment_failed
   • Click Add destination
   • Copy the Partner event source name (format: aws.partner/stripe.com/acct_xxx/evt-src-xxx)
   • In AWS Console -> Amazon EventBridge -> Partner event sources
   • Find your Stripe source and click Associate with event bus
   • Choose Associate with default event bus

Linking Customer Accounts

# Link AWS accounts to Stripe customers
ai-org billing link <aws-account-id> <stripe-customer-id>

# Example for Landline Scrubber
ai-org billing link 558232169845 cus_xxx  # Staging account
ai-org billing link 458894893282 cus_xxx  # Production account

# View all billing mappings
ai-org billing list

# Remove account from billing
ai-org billing unlink <aws-account-id>

How It Works

1. Monthly: Stripe automatically creates invoices for subscriptions
2. EventBridge: Receives invoice events from Stripe
3. Lambda: Calculates AWS costs (with 20% markup) and adds to invoice
4. Stripe: Handles payment collection, retries, and receipts

Testing vs Production

The system automatically uses TEST_STRIPE_SECRET_KEY when available for safe testing:

• Test mode uses Stripe's test environment (test customers, test payments)
• Production mode uses real payments when TEST_STRIPE_SECRET_KEY is not set
• Always test with test keys first before switching to production

GitHub Actions Setup

The bootstrap process creates a SAMDeployRole in each account. Your workflows just need:

name: Deploy
on:
  push:
    branches: [main, staging]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          # These are automatically created by ai-org!
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: us-east-1

      - run: sam deploy --config-env ${{ vars.ENVIRONMENT }}

🏗️ Architecture

Control Tower (AWS Managed)
├── Security OU
│   ├── Audit Account
│   └── Log Archive Account
├── Sandbox OU (Unrestricted)
└── Workloads OU (Your Domain)
    └── All workload accounts (both staging & production)

Key Design Principles

1. Zero-touch provisioning - Accounts self-configure based on OU
2. GitOps ready - GitHub Actions OIDC from day one
3. Cost conscious - Staging gets essentials, prod gets everything
4. Secure by default - SCPs enforce security baseline
5. Audit friendly - Centralized logging and compliance reports
6. Group-based admin access - The AIOrgAdmins Identity Center group gets AWSAdministratorAccess automatically on every new account via the account-lifecycle-hook Lambda. Manage admins by editing group membership in the Identity Center UI, not by running per-account CLI commands.

📚 Documentation

Resource	Description
API Reference	Complete CLI and module documentation
Architecture Guide	System design and decision rationale
Configuration Guide	Detailed config options and examples
Migration Guide	Migrating existing accounts
Development Guide	Contributing and local development

🔍 Prerequisites

Before running ai-org bootstrap:

• ✅ AWS Control Tower is activated
• ✅ AWS SSO configured with management account access
• ✅ AWS CLI v2 with SSO profile configured
• ✅ Python 3.12+ installed
• ✅ GitHub organization created (for OIDC)

🚧 Troubleshooting

Account Creation Issues

# Check account status
ai-org account info myapp --verbose

# View CloudFormation events
ai-org debug stackset-instances pipeline-bootstrap

# Verify OU structure
ai-org validate organization

Common Issues

• "Production OU not visible in Account Factory" → Run ai-org bootstrap --enable-baselines
• "StackSets not deploying" → Check account is in correct OU with ai-org account move
• "GitHub Actions can't authenticate" → Verify with ai-org validate github-oidc

How to Contribute

Contributions are made through AI agents (Claude Code, Copilot, etc.). You describe what you want changed in plain language; the agent handles branching, coding, testing, and submitting a pull request.

1. Open Claude Code (or your AI agent) in this repo.
2. Describe the change you want -- a bug fix, a new feature, a doc update.
3. The agent will:
   • Create a feature branch
   • Make the changes
   • Run pre-commit checks and tests
   • Open a pull request
4. Review the PR when the agent is done. CI runs automatically.
5. Merge once CI is green.

If you need to work manually, see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with:

• AWS Control Tower for landing zone management
• uv for blazing fast Python tooling
• python-semantic-release for automated versioning
• pdoc for documentation generation

---

Stop clicking through AWS Console. Start shipping.