kolja-aws 0.4.3

AWS SSO CLI Tool

Kolja AWS CLI Tool 🚀

A powerful CLI tool that simplifies AWS SSO login management and AWS profile configuration. It automatically manages SSO sessions, generates AWS profiles, and provides seamless shell integration for quick profile switching, making it easier to work with multiple AWS accounts and roles.

✨ Features

• Automatic Profile Generation: Automatically create AWS profiles for all accessible accounts and roles
• SSO Session Management: Easy setup and management of multiple SSO sessions
• Shell Integration: Built-in interactive AWS profile switcher with sp command
• Profile Switcher Integration: Works seamlessly with AWS profile switcher tools like Granted

🚀 Installation

uv tool install kolja_aws

Or install from source:

git clone https://github.com/koljahuang/kolja_aws.git
cd kolja_aws
poetry install

Shell Integration Setup

After installation, the shell integration is automatically configured during the installation process. If automatic setup fails, you can manually install it:

kolja-install-shell

This adds the sp command to your shell configuration file (.bashrc, .zshrc, or .config/fish/config.fish).

⚙️ Configuration

Interactive Setup

No configuration files needed! The tool uses interactive prompts to gather all necessary information.

When you run kolja aws set <session_name>, you'll be prompted for:

• SSO Start URL: Your organization's SSO URL (e.g., https://xxx.awsapps.com/start)
• SSO Region: AWS region for your SSO (e.g., ap-southeast-2, cn-northwest-1)

The system automatically sets registration scopes to sso:account:access.

🔒 Security Features

• No configuration files: Eliminates risk of accidentally committing sensitive SSO URLs
• Interactive input only: All sensitive data entered through secure prompts, never stored in files
• No sensitive data in repository: Since all configuration is interactive, there's no risk of committing sensitive information

📖 Usage

Available Commands

kolja aws --help

Usage: kolja aws [OPTIONS] COMMAND [ARGS]...

AWS SSO session and profile management commands.

Use these commands to interactively configure SSO sessions,
login to AWS, and generate profiles for your accounts.

Options:
  --help  Show this message and exit.

Commands:
  get       List all configured SSO sessions
  login     Login to all configured SSO sessions
  profiles  Generate AWS profile sections for all available accounts and roles
  set       Configure an SSO session through interactive prompts

Shell Integration Commands

After installation, you can use these commands in your terminal:

# Interactive AWS profile switcher
sp

# Manual shell integration setup (if needed)
kolja-install-shell

# Diagnose shell integration issues
kolja-diagnose

Step-by-Step Workflow

1. Configure SSO Sessions

Set up your SSO sessions interactively:

kolja aws set my-company

You'll be prompted to enter:

• SSO start URL (e.g., https://your-company.awsapps.com/start)
• SSO region (e.g., ap-southeast-2)

The tool will guide you through each step with examples and validation.

Check your configured sessions:

kolja aws get

2. Login to SSO

kolja aws login

3. Generate AWS Profiles

Automatically create profiles for all accessible accounts and roles:

kolja aws profiles

This generates profiles with the format [profile AccountID-RoleName]:

[profile 123456789012-AdminRole]
sso_session = kolja-cn
sso_account_id = 123456789012
sso_role_name = AdminRole
region = cn-northwest-1
output = text

[profile 123456789012-ReadOnlyRole]
sso_session = kolja-cn
sso_account_id = 123456789012
sso_role_name = ReadOnlyRole
region = cn-northwest-1
output = text

4. Use the Built-in Profile Switcher

Use the integrated sp command for quick profile switching:

sp

This opens an interactive menu with smooth arrow key navigation:

🔄 AWS Profile Switcher
Use ↑↓ arrow keys to navigate, Enter to select, Ctrl+C to cancel

? Select AWS Profile:
❯ 🟢 123456789012-AdminRole (current)
     123456789012-ReadOnlyRole
     987654321098-DeveloperRole

After selection, the AWS_PROFILE environment variable is automatically set:

✅ Switched to profile: 123456789012-AdminRole

5. Alternative: Use with External Profile Switchers

You can also use your favorite AWS profile switcher. Example with Granted:

assume -c

? Please select the profile you would like to assume:  [Use arrows to move, type to filter]

> 123456789012-AdminRole
  123456789012-ReadOnlyRole
  987654321098-DeveloperRole

🔄 Shell Integration

The shell integration feature provides a seamless way to switch between AWS profiles directly from your terminal.

Features

• Smooth Arrow Key Navigation: Navigate through available profiles with ↑↓ arrow keys
• Interactive Profile Selection: Modern, user-friendly selection interface
• Automatic Environment Setup: Sets AWS_PROFILE environment variable automatically
• Multi-Shell Support: Works with Bash, Zsh, and Fish shells
• Safe Installation: Creates backups before modifying shell configuration files
• Current Profile Highlighting: Shows which profile is currently active with 🟢 indicator

Supported Shells

Shell	Configuration File	Status
Bash	~/.bashrc, ~/.bash_profile	✅ Supported
Zsh	~/.zshrc	✅ Supported
Fish	~/.config/fish/config.fish	✅ Supported

Installation Process

1. Automatic Detection: Detects your current shell environment
2. Backup Creation: Creates timestamped backups of configuration files
3. Script Integration: Adds the sp function to your shell configuration
4. Validation: Verifies the installation was successful

Usage Examples

# Basic usage - opens interactive menu
sp

# Check current profile
echo $AWS_PROFILE

# Verify installation
kolja-install-shell --help

# Run demo (from source)
python examples/shell_integration_demo.py

For more comprehensive examples, see EXAMPLES.md.

Troubleshooting

If the shell integration doesn't work:

1. Run diagnostics: kolja-diagnose (comprehensive system check)
2. Reload your shell: source ~/.zshrc (for zsh) or source ~/.bashrc (for bash) or restart terminal
3. Manual installation: Run kolja-install-shell
4. Check shell support: Ensure you're using a supported shell
5. Verify AWS profiles: Run kolja aws profiles to generate profiles first

🏗️ Architecture

• Interactive Configuration: No configuration files needed - all settings gathered through interactive prompts
• In-Memory Processing: Configuration data is processed in memory and written directly to AWS config
• Profile Management: Creates and updates AWS profiles with AccountID-RoleName format
• Shell Integration: Seamless terminal integration with automatic environment variable management
• Validation: Built-in validation for SSO URLs and AWS regions

📖 New Feature: Built-in shell integration with the sp command provides instant AWS profile switching without external tools.

📚 Documentation

• Usage Examples: Comprehensive examples and use cases
• Troubleshooting Guide: Solutions to common issues
• Changelog: Version history and release notes

🧪 Testing

Run the test suite:

pytest

🔐 Security

With the new interactive configuration system, security is greatly simplified:

Security Benefits

• No sensitive data in repository: All SSO URLs and configuration entered interactively
• No configuration files to secure: Eliminates the risk of accidentally committing sensitive information
• Clean git history: No need for sanitization scripts or git hooks
• Simple and secure: No complex security setup required

Best Practices

1. Use the interactive prompts to configure SSO sessions - no files to manage
2. All sensitive data stays local in your ~/.aws/config file
3. Review generated AWS profiles in ~/.aws/config after running kolja aws profiles
4. The repository contains no sensitive information by design

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.