augint-org 0.7.0

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/Production, Workloads/Staging)
# ✅ 7 StackSets with auto-deployment
# ✅ Service Control Policies
# ✅ GitHub Actions authentication
# ✅ Cost management and monitoring

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

🔧 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)
    ├── Production OU
    │   └── [project]-prod accounts (Full automation)
    └── Staging OU
        └── [project]-staging accounts (Essential automation)

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

📚 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

🤝 Contributing

We welcome contributions! 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.