Table of Contents

aws-bash-toolbox (AWS CLI + SSO + SSM) 🧰
#

Status: alpha (breaking changes are allowed).

A Bash toolkit that gives you a kubectx/kubens-style workflow for AWS:

Active context: persistent AWS_PROFILE + AWS_REGION
Fast switching: abt change ... / abt select context (with fzf)
EC2 listing without the console: abt list ec2
SSM Session Manager connect: abt connect ssm / abt select ssm
SSM port forwarding to private services: abt connect forward / abt select forward
Corporate VPN/proxy workaround: SSM ignores proxy only during sessions
Utilities: abt list profiles/regions, abt show identity, abt test doctor, abt sso login

Repository: https://github.com/sondosclick/aws-bash-toolbox.git

Requirements
#

Linux (tested on Ubuntu 24.04)
Bash
AWS CLI v2
IAM Identity Center (SSO) access

Install dependencies:

sudo apt update
sudo apt install -y fzf session-manager-plugin

Verify:

aws --version         # should be aws-cli/2.x
session-manager-plugin

Profile naming convention (recommended)
#

We use:

corp-<env>-<role>

Examples:

corp-dev-readonly
corp-uat-admin
corp-pro-support

Where:

<env>: target environment (e.g., dev, uat, pro)
<role>: permission set / role in IAM Identity Center (e.g., admin, readonly, support)

If your team uses other names (sandbox, np, prod, etc.), adjust as needed. The important part is consistency.

1) Configure AWS SSO (profiles)
#

This toolbox assumes AWS SSO profiles in ~/.aws/config.

1.1 Create/validate the SSO session
#

In ~/.aws/config:

[sso-session corp-sso]
sso_start_url = https://<YOUR_START_URL>/start
sso_region = eu-central-1
sso_registration_scopes = sso:account:access

Important: use the Start URL without /#/ to avoid token/cache issues.

1.2 Create profiles per account and role (permission set)
#

Full examples:

[profile corp-dev-admin]
sso_session = corp-sso
sso_account_id = 111111111111
sso_role_name = admin
region = eu-west-3
output = json

[profile corp-uat-readonly]
sso_session = corp-sso
sso_account_id = 222222222222
sso_role_name = readonly
region = eu-west-3
output = json

[profile corp-pro-support]
sso_session = corp-sso
sso_account_id = 333333333333
sso_role_name = support
region = eu-west-3
output = json

Note: for SSO the correct pattern is sso_session + sso_account_id + sso_role_name. Avoid source_profile + role_arn unless your org explicitly requires classic AssumeRole.

1.3 Optional: assume an extra role after SSO login (SSM full access)
#

If your org requires a second role after SSO (common for elevated access), create a chained profile that uses source_profile and role_arn.

Example: assume a custom SSM full-access role after logging in with an existing SSO profile that ends in assumerole:

[profile corp-br-np-assumerole]
sso_session = corp-sso
sso_account_id = 418272778142
sso_role_name = AssumeRole
region = eu-west-3
output = json

[profile corp-br-np-ssmfullaccess]
role_arn = arn:aws:iam::418272778142:role/ssmfullcaccess
source_profile = corp-br-np-assumerole
role_session_name = your-user
region = eu-west-3

ASCII flow:

You
  │
  ├─(SSO login)─> corp-br-np-assumerole
  │                (Identity Center permission set)
  │
  └─(AssumeRole)→ corp-br-np-ssmfullaccess
                   (ssmfullcaccess)

When to use which:

Use the assumerole profile only to log in to SSO.
Use the ssmfullaccess profile for commands that need the extra role.

Simple use:

# 1) Log in with the SSO session
abt sso login corp-sso

# 2) Switch to the derived role profile
abt change profile corp-br-np-ssmfullaccess
aws sts get-caller-identity

If you have many *-assumerole profiles, repeat the second block for each one, keeping source_profile pointed to its matching base profile and the same role_arn pattern (ssmfullcaccess).

2) SSO login
#

If you changed profiles or saw errors:

rm -rf ~/.aws/sso/cache/*

aws sso login --sso-session corp-sso

Verify:

aws sts get-caller-identity --profile corp-dev-admin --region eu-west-3

3) Install the toolbox
#

Method A) Automated install (recommended)
#

git clone https://github.com/sondosclick/aws-bash-toolbox
cd aws-bash-toolbox
./install.sh
source ~/.bashrc

What install.sh does:

copies abt.sh to ~/.abt/abt.sh
adds a line to ~/.bashrc:

source "$HOME/.abt/abt.sh"

It does not overwrite your bashrc and is safe to run multiple times.

Method B) Manual (copy/paste)
#

Clone the repo:

git clone https://github.com/sondosclick/aws-bash-toolbox

Copy abt.sh to ~/.abt:

mkdir -p "$HOME/.abt"
cp abt.sh "$HOME/.abt/abt.sh"

Edit your ~/.bashrc and add at the end:

source "$HOME/.abt/abt.sh"

Reload:

source ~/.bashrc

4) Optional configuration (abt)
#

The toolbox can read an optional file: ~/.abt/abt.env (shell format).

Create a template:

abt config init

Force overwrite:

abt config init --force

Available variables (example):

ABT_DEFAULT_PROFILE="corp-base"
ABT_DEFAULT_REGION="eu-central-1"
ABT_REGIONS="eu-central-1 eu-west-1 eu-west-3 us-east-1 us-west-2"
ABT_COLOR=1

ABT_DEFAULT_*: used when no persisted context exists.
ABT_REGIONS: space-separated list used by selectors.
ABT_COLOR=0: disables colored output.

Show current config:

abt show config

5) Quick usage
#

Format: abt <verb> <object>

abt show context
abt show profile
abt show region
abt show identity
abt show version
abt export context
abt list profiles
abt list regions
abt change profile corp-uat-readonly
abt change region eu-west-3
abt change context corp-uat-readonly eu-west-3
abt select context
abt select profile
abt select region
abt list ec2
abt connect ssm i-0123456789abcdef0
abt connect ssm -n api-01
abt connect forward i-0123456789abcdef0 db.internal 5432
abt connect forward -n bastion-01 db.internal 5432 15432
abt select ssm
abt select forward
abt sso login
abt test sts
abt test sts eu-west-3 eu-central-1
abt test doctor
abt config init
abt show config

Tip: abt export context is handy for scripts:

source <(abt export context)

6) Port forward to private services (SSM)
#

Use an SSM-managed instance (bastion) as a tunnel from your laptop to a private service (RDS, Redis, internal API, etc.). This avoids SSH and works with IAM Identity Center.

Start a port-forward session:

# Forward local 15432 -> db.internal:5432 through a bastion
abt connect forward -n bastion-01 db.internal 5432 15432

# If local port is omitted, it defaults to the remote port
abt connect forward i-0123456789abcdef0 db.internal 5432

Interactive (fzf) flow with a common DB port picker:

abt select forward

Tip: add a tag on the bastion to prefill the remote host:

ForwardHost (preferred)
DBHost, DbHost, DBEndpoint, RDSEndpoint, RDSHost, db_host

Then connect your client (e.g., DBeaver) to:

Host: 127.0.0.1
Port: 15432   # or 5432 if you didn't override local port

Example: RDS (PostgreSQL)

abt connect forward -n bastion-01 mydb.abc123.eu-west-3.rds.amazonaws.com 5432 15432

Security group rules to make this work:

RDS SG inbound: allow 5432 from the bastion instance SG.
Bastion SG outbound: allow 5432 to the RDS SG (if egress is restricted).
SSM requirements: instance has SSM agent + IAM role with AmazonSSMManagedInstanceCore.

Notes:

Keep the terminal open while the session is active (Ctrl+C to stop).
The instance must be SSM-managed and able to reach the remote host/port.

FAQ
#

“Error loading SSO Token: Token for <start_url> does not exist”
#

Fix:

rm -rf ~/.aws/sso/cache/*
aws sso login --sso-session corp-sso

Verify your profiles use sso_session = corp-sso.

`Cannot perform start session: EOF`
#

Likely corporate proxy/VPN. This toolbox ignores proxy only for SSM, but if it still fails:

try without VPN / another network (if possible)
inspect proxy env:

env | grep -i proxy

`session-manager-plugin: command not found`
#

Install:

sudo apt update
sudo apt install -y session-manager-plugin

No instances show up in `abt select ssm`
#

Check SSM Agent / permissions / connectivity:

aws ssm describe-instance-information \
  --profile <profile> --region <region> \
  --query 'InstanceInformationList[].{Id:InstanceId,Status:PingStatus,Agent:AgentVersion}' \
  --output table

Repo files
#

abt.sh -> Bash functions (toolbox)
install.sh -> installer (adds source ... to ~/.bashrc)
README.md -> documentation

License
#

GPL-3.0-only. See LICENSE.

aws-bash-toolbox (AWS CLI + SSO + SSM) 🧰#

Requirements#

Profile naming convention (recommended)#

1) Configure AWS SSO (profiles)#

1.1 Create/validate the SSO session#

1.2 Create profiles per account and role (permission set)#

1.3 Optional: assume an extra role after SSO login (SSM full access)#

2) SSO login#

3) Install the toolbox#

Method A) Automated install (recommended)#

Method B) Manual (copy/paste)#

4) Optional configuration (abt)#

5) Quick usage#

6) Port forward to private services (SSM)#

FAQ#

“Error loading SSO Token: Token for <start_url> does not exist”#

Cannot perform start session: EOF#

session-manager-plugin: command not found#

No instances show up in abt select ssm#

Repo files#

License#