awsui

Website

Stop wiring machine-specific AWS profile names into every command.
Choose an environment, verify the account, and launch Claude Code, Codex, Kiro, Terraform, or any CLI in the right AWS context.

You work in environments such as dev, staging, and prod. AWS tools work
with profile names such as company-payment-production-admin. awsui maps the
project environment to a local AWS profile, verifies the authenticated account,
and launches your tool only when the account matches the project configuration.

Initialize the project, bind a profile, verify the account, and launch a tool.

What problem does awsui solve?

You choose the environment. awsui handles the context checks behind it:

• Work with project environment names such as prod, not profile names that vary
  from one machine to another.
• See the account returned by AWS STS before a tool starts.
• Run AI agents, Terraform, AWS CLI, scripts, and shells in the same verified
  context.
• Share the expected account and region for each environment while keeping
  profile bindings local.
• Stop before launch when authentication fails or the account does not match.

[!IMPORTANT]
awsui verifies the AWS context at launch time; it is not a security sandbox.
After launch, a child process can still replace inherited environment variables
or explicitly select another profile.

Quick start

Complete these four steps to define a project context, verify the AWS identity,
and launch a tool inside that context.

Before you start

Install Python 3.13 and AWS CLI v2,
then configure at least one AWS profile through AWS CLI. IAM Identity Center
(SSO) is the recommended authentication method.

1. Install awsui

The recommended option is an isolated installation with
uv:

uv tool install --python 3.13 awsui

You can also install awsui in the current Python environment with pip:

pip install awsui

Verify the installation:

awsui --version

If awsui prints a version number, the installation is ready.

CLI output defaults to English. To switch to Traditional Chinese and save the
preference, run:

awsui --lang zh-TW

Run awsui --lang en to switch back. The option can also precede another
command, as in awsui --lang zh-TW context prod. awsui stores only the language
preference in ~/.config/awsui/settings.json; the file contains no AWS
credentials. If the settings file is invalid, explicitly setting --lang again
recreates it.

2. Initialize the project context

Move into the project directory and start the guided setup:

cd payment-service
awsui init

awsui prompts you to name the project, add environments, choose or create a
local profile, and verify each AWS identity. When setup finishes, it displays a
summary like this:

Created /path/to/payment-service/.awsui.yaml
Project: payment-service
  dev: 111111111111 · ap-northeast-1
  prod: 999999999999 · ap-northeast-1 · PROTECTED

awsui writes the shared environments, accounts, and regions to .awsui.yaml.
Machine-specific profile bindings remain outside the repository.

Create the shared project contexts from the terminal.

3. Verify the environment you are about to use

Before launching a tool, check which AWS identity is actually behind prod:

awsui context prod

The output shows both the expected and authenticated accounts:

payment-service · PROD · PROTECTED
Expected account: 999999999999
Authenticated account: 999999999999
Region: ap-northeast-1
Local profile: company-payment-prod
Status: ✓ VERIFIED

Confirm that the expected and authenticated accounts match. VERIFIED means
the context is available; this command reports the result without launching a
child process.

Confirm the authenticated AWS account before launching a tool.

4. Launch your tool

Once the context is ready, launch the tool you need:

awsui prod -- codex
awsui prod -- claude
awsui prod -- terraform plan

Immediately before launch, awsui verifies the identity again and displays the
context that the child process will receive:

payment-service · PROD · PROTECTED
Account: 999999999999 ✓
Region: ap-northeast-1
Launching: codex

If the account does not match the project configuration, awsui displays
AWS CONTEXT MISMATCH and Command was not started., then stops without
launching the command.

awsui launches Codex only after the selected context passes verification.

Run awsui --help to see every command. To open an interactive shell with a
verified context, run awsui dev.

After another developer checks out the repository, they only need to bind the
shared prod environment to a profile on their machine:

awsui bind prod
awsui prod -- claude

Each developer binds the shared environment name to a local profile.

What the team commits and what stays local

Record the expected account and region for each environment in .awsui.yaml,
then commit that file to the repository:

version: 1
project: payment-service
contexts:
  dev:
    account: "111111111111"
    region: ap-northeast-1
  qa:
    account: "222222222222"
    region: ap-northeast-1
  staging:
    account: "333333333333"
    region: ap-northeast-1
  prod:
    account: "999999999999"
    region: ap-northeast-1
    protected: true

Every developer uses the same environment names and account validation rules
without sharing profile names. awsui stores machine-specific bindings outside
the repository in ~/.config/awsui/bindings.json. Never put credentials in
.awsui.yaml.

Command reference

These are the primary CLI commands:

awsui context ls/list and awsui bind ls/list only read local
configuration; they do not contact AWS. They show the expected account, region,
protection status, and local profile for each context. Run
awsui context <environment> when you need to verify a specific context with
STS.

The explicit forms are also available:

awsui run prod -- codex
awsui shell prod

Content after -- is launched directly as an argument vector without shell
parsing. For pipes, redirects, &&, or other shell syntax, first open a verified
shell with awsui <environment>, then run the composed command inside it.

Need a new AWS profile?

If the profile you need does not exist, choose Create new AWS profile during
initialization or binding. IAM Identity Center (SSO) is the recommended first
option. awsui starts the official aws configure sso, aws login, or
aws configure workflow, then returns and selects the new profile.

You can also configure and verify an SSO profile before running awsui:

aws configure sso
aws sso login --profile my-company-dev
aws sts get-caller-identity --profile my-company-dev

AWS Console Login and access-key configuration are also available, but
long-lived access keys are not recommended. awsui uses credentials managed by
AWS CLI and does not store AWS credentials itself.

How does awsui verify a launch context?

Before every launch, awsui performs the following steps:

1. Resolves the project environment and its local profile binding.
2. Authenticates the selected profile when required.
3. Calls STS GetCallerIdentity.
4. Compares the authenticated account with the expected 12-digit AWS account ID.
5. Builds a child environment with credential overrides removed.
6. Starts the child process only when the accounts match.

An account mismatch or unverifiable identity stops the launch. Shared project
configuration contains no access keys, secret keys, session tokens, or local
profile names.

Need help or want to contribute?

If you find a bug, have a question, or want to suggest a feature, open a
GitHub Issue. Pull requests are
also welcome.

Set up a local development environment:

git clone https://github.com/junminhong/awsui.git
cd awsui
uv sync

Before opening a pull request, run:

uv run ruff check .
uv run pytest
uv build

License

MIT