diff --git a/README.md b/README.md
index fc5cfd8..25c278e 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,30 @@ IAMy is a tool for dumping and loading your AWS IAM configuration into YAML file
 
 This allows you to use a "Infrastructure as Code" model to manage your IAM configuration, and allows you to operate configuration and change management on a higher level. For example, you might use a github repo with a pull request model for changes.
 
+
+## How it works
+
+IAMy has two subcommands.
+
+`pull` will sync IAM users, groups and policies from AWS to YAML files
+
+`push` will sync IAM users, groups and policies from YAML files to AWS
+
+For the `push` command, IAMy will output an execution plan as a series of [`aws` cli](https://aws.amazon.com/cli/) commands which can be optionally executed. This turns out to be a very direct and understandable way to display the changes to be made, and means you can pick and choose exactly what commands get actioned.
+
+
+## Getting set up
+
+Because IAMy uses the aws cli tool, you'll want to install it
+
+To install the aws cli on macOS with brew:
+```
+brew install awscli
+```
+
+For configuration, IAMy uses the same [AWS environment variables](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-environment) as the aws cli.
+
+
 ## Usage
 
 ```bash
diff --git a/iamy/awssession.go b/iamy/awssession.go
index d8531a9..f20f781 100644
--- a/iamy/awssession.go
+++ b/iamy/awssession.go
@@ -1,12 +1,24 @@
 package iamy
 
-import "github.com/aws/aws-sdk-go/aws/session"
+import (
+	"log"
+
+	"github.com/aws/aws-sdk-go/aws/session"
+)
 
 var sess *session.Session
 
 func awsSession() *session.Session {
 	if sess == nil {
-		sess = session.New()
+		var err error
+		sess, err = session.NewSessionWithOptions(session.Options{
+			SharedConfigState: session.SharedConfigEnable,
+		})
+
+		if err != nil {
+			log.Fatal("awsSession: couldn't create an AWS session", err)
+		}
 	}
+
 	return sess
 }