Skip to content

Home

Sketch fonts

whoiam is a lightweight CLI that keeps you oriented across multiple AWS accounts.

Made with VHS

Modern AWS setups involve a lot of accounts. Development, staging, production, sandboxes, client environments — and engineers switching between them constantly. Most credential tools are great at getting you into an account. whoiam answers the question you need answered before you act: am I in the right one?

How it works

Before any command runs, whoiam calls sts:GetCallerIdentity and compares the result against the account you declared you expected to be in. If they match, the command runs. If they don't, it exits immediately — before a single byte of infrastructure changes.

You declare your account map once (and commit it to your repo so the whole team shares it). Then you pin the expected environment for your current session with whoiam set. From that point on, whoiam exec and whoiam validate enforce it automatically.

Works with whatever you already use

whoiam is credential-agnostic. It works with AWS SSO, aws-vault, raw ~/.aws/credentials, instance profiles — anything the AWS SDK can resolve. It doesn't manage credentials itself; it just verifies them.

The expected environment can be set in whichever way fits your workflow:

  • AWS_PROFILE — if the profile name matches an account in your config, whoiam picks it up automatically
  • WHOIAM_EXPECTED_ENV — set the expected account inline or from a CI variable
  • whoiam set — pin it for your session so you don't repeat it on every command

Pin your session once, then run freely:

whoiam set development
whoiam exec -- terraform apply

Or pass the expected account inline:

AWS_PROFILE=production whoiam exec -- terraform apply
WHOIAM_EXPECTED_ENV=staging whoiam validate

Features

  • Verify before you act — asserts the right account before any command runs, so context switches don't turn into incidents
  • Multi-account aware — map all your environments (dev, staging, production, sandbox) in one config and switch between them with a single command
  • Works with any credential source — aws-vault, SSO, instance profiles, environment variables; if the AWS SDK can see it, whoiam can verify it
  • AWS_PROFILE support — if your profile name matches an account in your config, whoiam uses it automatically; no extra flags needed
  • Shareable account map — commit .whoiam/whoiam.yaml so the whole team uses the same account IDs; personal session state stays out of git
  • CI and pipeline friendly — whoiam validate exits non-zero on mismatch, making it a drop-in pre-flight check for any pipeline

Quick Start

Initialize a project-local config:

whoiam init

Edit .whoiam/whoiam.yaml to add your account mappings:

accounts:
  production:  "123456789012"
  staging:     "210987654321"
  development: "345678901234"

Pin the expected environment for this session:

whoiam set production

Run commands safely — whoiam verifies the account first:

whoiam exec -- terraform apply

Documentation

  • Installation — Homebrew, binary download, or build from source
  • Usage — all commands with examples
  • Configuration — config files, merging, session state, and environment variables