Home

General Usage

Running the awskeyring command without arguments will display a list of commands available.

Setup

First step is to create your macOS Keychain to store your AWS Access Keys into.

$ awskeyring initialise

You can specify the keychain name as an argument (see help), otherwise it will prompt you and then fall back to a default of "awskeyring". The keyring is accessible in the "Keychain Access" Utility. It will also auto-lock after 5 minutes.

Next you need to add Keys to the keychain.

$ awskeyring add ACCOUNT

You can script adding keys by providing them with arguments but the interactive prompt will catch them too.

Adding roles allows you to assume roles including across account too.

$ awskeyring add-role ROLE

If you already had credentials saved to the .aws/credentials file, you can import them one at a time by name.

$ awskeyring import ACCOUNT

Using Credentials

The basic way of using credentials is to take the output of the "env" command and use that to set your environment. A quick way is to run the following to do this in a single command.

$ eval "$(awskeyring env my-aws-account)"

This will set the environment variables allowing a variety of tools to access AWS APIs.

Alternatively you can run a single command with the environment variables set. After the command exits the environment variables will no longer exist.

$ awskeyring exec my-aws-account aws sts get-caller-identity

To assume a role, use an MFA or both you need to run the "token" command to generate a time limited token (that will be saved into the keychain until it expires) before running the "env" command.

$ awskeyring token ACCOUNT [ROLE] [MFA]

To just open up the AWS Console (web page) with your default browser simply run...

$ awskeyring console ACCOUNT

It requires permissions to run getFederationToken and getSigninToken and will try to use the session token if you have one.

For more details on a command you can ask the built in help function.

$ awskeyring help token