Skip to main content

Helper to easily assume IAM roles in AWS

Project description

AWS Assume Role Helper

Build Status

assume is a simple CLI utility that makes it easier to switch between different AWS roles. This is helpful when you work with different AWS accounts or users. In addition, this utility is helpful when you develop AWS resources locally (such as an application that will run on EC2 or when running a Lambda function locally using AWS SAM). You can easily switch to a role that your EC2 instance / Lambda function will assume in AWS.

What this command actually does is change your AWS credentials file (~/.aws/credentials). If there is a default role in there, it will be stored in a temporary role. The assumed role is then passed in the default role, so you can immediately start using it.

Table of Contents


Install Python. Versions 3.5 and 3.6 are supported.


Use pip to install `assume':

pip install assume

Run the following to show all available commands:

assume --help


Add a new role to assume as follows:

assume add [rolename] --role-arn [arn] --profile [profile]

Specifying the profile is optional. When you don't specify this, the default profile is used. The following would add a new role "myrole" to be assumed:

assume add myrole --role-arn arn:aws:iam::012345678912:role/myrole

You can now assume this role as follows:

assume switch myrole

assume keeps a configuration file in ~/.assume/config.yaml. You can list the contents of the current configuration with the following file:

assume list

When you want to switch back to your initial default role, you can clear the assumed role as follows:

assume clear

To remove a role to be assumed, run the following command:

assume remove myrole

This command grabs the default role that was stored in a temporary location when running the switch command. These credentials are then put back in the default role.


I'm aware that a number of alternatives already exist with similar functionality. The reason I decided to build my own functionality is because I wasn't be able to find an existing option that combines all of the following features:

  • Easy switching using shortcuts
  • Easily remove the temporarry role and switch back to the original one

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for assume, version 0.4.0
Filename, size File type Python version Upload date Hashes
Filename, size assume-0.4.0-py3-none-any.whl (5.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size assume-0.4.0.tar.gz (4.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page