by mheffner

mheffner / awsam

Amazon Web Services Account Manager (modeled after 'rvm')

123 Stars 8 Forks Last release: Not found MIT License 138 Commits 10 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

AWSAM (Amazon Web Services Account Manager) allows you to easily manage multiple sets of AWS credentials. It has support for multiple accounts and multiple key-pairs per account.

Account switching auto-populates ENV vars used by AWS' command line tools and AWSAM additionally gives you intelligent wrappers for

which can be used like:
# ssh by AWS instance id
$ assh [email protected]

ssh by AWS tag name

$ assh [email protected]

ssh by AWS tag name to an arbitrary node using a substring


This example assumes you have the following nodes and that

you're indifferent to which node you connect to:

web-node-01, web-node-02, web-node-3

$ assh -f [email protected]

scp by instance id

$ ascp local-file [email protected]:remote-file

AWSAM supports both AWS' legacy Java-based CLI tools and their newer python-based CLI.


  1. Install the gem.

    $ gem install awsam
  2. Install BASH rc file

    $ raem --init
    Initialized AWS Account Manager

    Add the following to your .bashrc:

    if [ -s $HOME/.awsam/bash.rc ]; then source $HOME/.awsam/bash.rc fi

  3. Open a new bash environment.

Environment variables

AWS Account Manager will set a variety of environment variables when you execute the

shell wrapper:
$ env | grep AMAZON_ACCESS
Exit 1
$ aenv env | grep AMAZON_ACCESS

Some of these environment variables match the ones used by the Amazon EC2 CLI tools and some our unique to AWSAM. It is often convenient to use these environment variables in DevOPs scripts in place of hard-coded values -- allowing your scripts to be seamlessly used for staging and production environments simply by switching the active account with

and wrapping execution of the command with

The environment variables set when selecting an account are:

    - API access key
    - Secret API access key
    - The integer ID of this AWS account

When selecting an SSH key, the following environment variables are set:

    - Name of the keypair.
    - Full path to the public key PEM file

NOTE: As of version 0.2.0, these are no longer set in the shell environment by default. You must run any command that requires AWS access with the



  1. Update repo (fetch && merge) or

    gem update awsam
  2. Run

    raem --init
    . Ignore instructions to setup .bashrc if you've already done so.
  3. Close and reopen your shell or

    source ~/.bashrc

General Usage

Add an account

If the environment already contains AWS variables, these will be presented as defaults.

$ aem add
Creating a new AWS account...
Short name: staging
Description: Staging account
AWS Region [us-east-1]: us-east-1
Access key [12346]: 123 *from AWS credentials*
Secret key [secret123456]: 455 *from AWS credentials*
AWS ID: aws_account

Note: if your shell can't find the

command it is most likely because you haven't successfully sourced
in the install steps.

Select the active account

This will update the current environment with the appropriate AWS environment variables.

$ aem use staging

When selecting an account you can mark it as the default account with the

$ aem use --default staging

List accounts

The active account will be marked with an arrow. The default, if set, will be marked with an asterisk.

$ aem list

AWS Accounts:

prod [Librato Production] [1 key: my-prod-key] => staging [Staging account] *dev [Librato Development] [1 key: devel-key]

Import a key pair

Add a key to the default account, or the specified account. Defaults chosen from current environment if set. IMPORTANT:

must match the logical name of the AWS EC2 keypair.
$ aem key add my-key-name /path/to/my-keypair.pem
Imported key pair my-key-name for account staging [Staging account]

The keypair must match the name of the keypair in AWS

Select a key

This will select an SSH keypair to use from your current account and set the environment variables

appropriately. It will also highlight the key in the list output with the '>' character.
$ aem key use my-key-name

$ aem list

AWS Accounts:

staging [Staging account] => dev [Librato Development] [1 key: >my-key-name]

You can also define a default key for each account that will automatically be selected when the account is chosen. Just use the

option when selecting a key to set a default key. Picking a default will place an asterisk next to the key name in the
$ aem key use --default my-key-name

aenv utility: wrap command execution with AWS environment


utility will wrap execution of any command with the AWS environment variables matching the currently selected account. This allows you to securely propagate environment variables only to commands that should have access to the current environment. Just prefix your command execution with
$ aenv aws s3 ls

assh utility: SSH by instance ID

Instance IDs will be looked up using the current account details. If the instance's keypair name exists, that keyfile will be used as the identity file to ssh.


$ assh [[email protected]]


$ assh [email protected]
warning: peer certificate won't be verified in this SSL session
Loging in as ubuntu to


[email protected]:~$

assh utility: SSH by tag name

Instances will be looked up by their tag name. This tag name can be found assigned to the "value" key when you run ec2-describe-tags, using the AWS CLI Tools.


$ assh [[email protected]]


$ assh [email protected]
warning: peer certificate won't be verified in this SSL session
Loging in as ubuntu to


[email protected]:~$

If you use assh with a substringed tag name which matches against several nodes, you will have the option to choose a specific node. For example, let's say you have 3 nginx nodes all running the same code and your nodes are named:

web-node-01, web-node-02, web-node-03

Then you run the following from within your terminal:


$ assh [email protected]
Please select which node you wish to use:
0) web-node-01 (i-43dfed45)
1) web-node-02 (i-789eft24)
2) web-node-03 (i-546fer56)
> 1

You'll notice that you're given a list of the nodes in your account that match the "web-node-*" pattern. The instance ID associated with each node is appended to each option as well. You will then be given a prompt (>) where you enter the index of the node you want to connect to.

Finally, if you use assh with a substringed tag name using the -f option, you can pass the base substring of a cluster of common nodes to connect to an arbitrary node within that cluster. The -f option assumes you have 'n' number of machines using a shared base name, all running mirrored environments. Once again, we will use the web-node-[01,02,03] scenario from our previous example:


$ assh -f [[email protected]]web-node-

In this example, you would automatically connect to one of the machines in your account which matches the "web-node-*" pattern without having to explicitly choose a node.

assh utility: questions/help?

Run the following from your terminal:

$ assh --help


$ assh -h

ascp utility: SCP by instance ID

Instance IDs will be looked up using the current account details. If the instance's keypair name exists, that keyfile will be used as the identity file to scp.


$ ascp [[email protected]]:remote-file local-file
$ ascp local-file [[email protected]]:remote-file

Default user

You can specify a default user to assh by setting

$ AWS_DEFAULT_USER=ubuntu assh datanode
Please select which node you wish to use:

  1. metrics_facing-stg-v2-datanode-11 (i-30XXXXX, m1.large, 2014-02-12T20:46:29.000Z)
  2. metrics_facing-stg-v2-datanode-12 (i-91XXXXX, m1.large, 2014-02-13T04:20:32.000Z)
  3. metrics_facing-stg-v2-datanode-13 (i-64XXXXX, m1.large, 2014-03-04T18:59:26.000Z) q) Quit

> 2

Logging in as ubuntu to

Remove a key

You can remove ah SSH key from an account (defaults to the current account).

$ aem key remove --acct prod my-prod-key

Remove an account

You can remove an account as long as it is not the active one.

$ aem remove staging

Contributing to awsam

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
  • Fork the project
  • Start a feature/bugfix branch
  • Commit and push until you are happy with your contribution
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.


assh utility:

  • ssh to a tag name (multiple?)
  • caches instance id => hostname for fast lookup
  • determines user?
  • supports complete SSH CLI options
  • inline commands, eg:
    ssh [email protected] sudo tail /var/log/messages


Copyright (c) 2011 Mike Heffner. See LICENSE.txt for further details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.