Setlist is a CLI tool that automates the creation of AWS config files for organizations using AWS SSO. It parses AWS Organizations and Permission Sets to build a complete .aws/config file with all permission sets provisioned across your AWS member accounts.
Managing AWS credentials across multiple AWS accounts with SSO can be challenging. While AWS provides the aws sso configure command, it's tedious to use when you have:
- Multiple AWS accounts in your organization
- Multiple permission sets per account
- Teams that need consistent configuration
Setlist solves this by automatically generating a complete .aws/config file with profiles for all accounts and permission sets you have access to, saving you time and preventing configuration errors.
Download the latest release from the GitHub Releases page.
# Clone the repository
git clone https://github.com/scottbrown/setlist.git
cd setlist
# Install Task (if not already installed)
brew install go-task
# Build the binary
task build
# The binary will be available at .build/setlist- AWS CLI installed
- AWS SSO configured for your organization
- AWS credentials with permissions to access AWS Organizations and SSO Admin APIs
This tool requires some readonly permissions from your AWS organization account. They are:
organizations:ListAccountssso:ListInstancessso:ListPermissionSetsProvisionedToAccountsso:DescribePermissionSet
You can view these in the application by running:
setlist --permissions# Generate AWS config using the organization's SSO instance
setlist --sso-session myorg --sso-region us-east-1 --output ~/.aws/config# Use an existing AWS profile to authenticate
setlist --sso-session myorg --sso-region us-east-1 --profile admin --output ~/.aws/config# Map account IDs to friendly names
setlist --sso-session myorg --sso-region us-east-1 \
--mapping "123456789012=prod,210987654321=staging" \
--output ~/.aws/config# Output to stdout instead of a file
setlist --sso-session myorg --sso-region us-east-1 --stdout# Use a friendly name instead of the identity store ID
setlist --sso-session myorg \
--sso-region us-east-1 \
--sso-friendly-name my-company \
--output ~/.aws/configBy supplying a --mapping flag with a comma-delimited list of key=value pairs corresponding to AWS Account ID and its nickname, the tool will create the basic .aws/config profiles and then create a separate set of profiles that follow the format [profile NICKNAME-PERMISSIONSETNAME]. For example: [profile acme-AdministratorAccess]. This removes the need for your users to remember the 12-digit AWS Account ID, but also allows for backward-compatibility for those people that like using the AWS Account ID in the profile name.
| Flag | Short | Description | Required |
|---|---|---|---|
| --sso-session | -s | Nickname for the SSO session (e.g., organization name) | Yes |
| --sso-region | -r | AWS region where AWS SSO resides | Yes |
| --profile | -p | AWS profile to use for authentication | No |
| --mapping | -m | Comma-delimited account nickname mapping (format: id=nickname) | No |
| --output | -o | Output file path (default: ./aws.config) | No |
| --stdout | Write config to stdout instead of a file | No | |
| --sso-friendly-name | Alternative name for the SSO start URL | No | |
| --list-accounts | Lists all available AWS accounts |
Setlist generates an AWS config file with:
- A default section specifying the SSO session
- An SSO session section with start URL, region, and registration scopes
- Profile sections for each account and permission set combination
Example:
[default]
# Generated on: 2025-02-27T10:15:30 UTC
sso_session = myorg
[sso-session myorg]
sso_start_url = https://d-12345abcde.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access
# Administrator access. Session Duration: PT12H
[profile 123456789012-AdministratorAccess]
sso_session = myorg
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
# Administrator access. Session Duration: PT12H
[profile prod-AdministratorAccess]
sso_session = myorg
sso_account_id = 123456789012
sso_role_name = AdministratorAccessSimplify the onboarding process for new team members by providing a single command that generates a complete AWS config with all the accounts and permission sets they need access to.
When permission sets change in your AWS Organization, quickly regenerate your config file to include the new permission sets without manual configuration.
Use Setlist in CI/CD pipelines to ensure consistent AWS configuration across different environments.
If you encounter permission errors, ensure your AWS credentials have access to:
- organizations:ListAccounts
- sso-admin:ListInstances
- sso-admin:ListPermissionSetsProvisionedToAccount
- sso-admin:DescribePermissionSet
The --sso-region parameter must specify the region where your AWS SSO instance is deployed, not necessarily the region where your resources are located.
Ensure you have write permissions to the output file location.
- Go 1.21 or newer
- Task
# Clone the repository
git clone https://github.com/scottbrown/setlist.git
cd setlist
# Run tests
task test
# Build for development
task build# Run all tests
task test
# Run security checks
task check# Build a release version
task release VERSION=v1.2.3cmd/: Command-line interface code*.go: Core functionality for AWS interactions and config generation.github/workflows/: CI/CD pipeline definitionsgo.mod, go.sum: Go module definitionstaskfile.yml: Task automation definitions
Contributions are welcome! Here's how to contribute:
- Fork the repository
- Create a feature branch:
git checkout -b my-new-feature - Make your changes and add tests if applicable
- Run tests to ensure everything passes:
task test - Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin my-new-feature - Submit a pull request
Each release comes with a software bill of materials (SBOM). It is generated using CycloneDX-GoMod using the following command:
cyclonedx-gomod mod -licenses -json -output bom.jsonReleases are typically automated via Github Actions whenever a new tag is pushed to the default branch.
This project is licensed under the MIT License - see the LICENSE file for details.
- Thanks to all contributors who have helped improve Setlist
- Built with Cobra and AWS SDK for Go v2