Usage

Initialize Config

Project-local (creates .whoiam/whoiam.yaml in the current directory):

whoiam init

This also creates a .whoiam/.gitignore that excludes expected-env from version control. Commit .whoiam/whoiam.yaml to share account mappings with your team.

Global (creates ~/.whoiam/whoiam.yaml):

whoiam init --global

---

Set the Expected Environment

Tell whoiam which account you expect to be authenticated with. This saves you from passing --env on every command.

Project-local (takes precedence over global):

whoiam set production

Global (applies across all projects):

whoiam set --global staging

To remove the expectation, use whoiam clear:

Clear local:

whoiam clear

Clear global:

whoiam clear --global

Use whoiam status to see what is currently set.

---

Check Status

Show the current expected environment and whether you are authenticated:

whoiam status

Example output:

Expected env:  production (local)
Authenticated: yes
Account:       production (123456789012)
ARN:           arn:aws:iam::123456789012:role/my-role

---

Validate

Assert that the current AWS credentials match the expected account. Exits non-zero on mismatch, making it suitable as a pre-flight check.

Using the expected env set by whoiam set:

whoiam validate

Explicit environment:

whoiam validate --env production

Use this in Taskfiles, CI pipelines, or mise hooks to fail fast before a destructive operation:

Taskfile:

tasks:
  deploy:
    cmds:
      - whoiam validate --env production
      - terraform apply

mise:

[hooks.enter]
run = "whoiam set development"

[tasks.deploy]
run = "whoiam exec --env production -- terraform apply"

---

Exec

Verify the expected account and then run a command. If the account matches, the command runs; if not, it exits before anything executes.

Run a command:

whoiam exec --env production -- terraform apply

Open an interactive subshell with the account already verified:

whoiam exec --env production

If you have already set the expected environment with whoiam set, omit --env:

whoiam set production
whoiam exec -- terraform apply

---

View Config

Print the effective merged configuration (global + project-local), showing the source of each account:

whoiam config

---

Command Reference

Command	Description
whoiam init	Initialize project-local config
whoiam init --global	Initialize global config
whoiam set <env>	Set the local expected environment
whoiam set --global <env>	Set the global expected environment
whoiam clear	Clear the local expected environment
whoiam clear --global	Clear the global expected environment
whoiam status	Show expected env and current auth state
whoiam validate [--env <env>]	Assert current account matches expected
whoiam exec [--env <env>] [-- cmd]	Verify account then run command or open subshell
whoiam config	Print merged config with sources