brolly 0.1.0__py3-none-any.whl

brolly/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.1.0'

brolly/__main__.py

@@ -0,0 +1,4 @@
+from brolly.cli import app
+
+if __name__ == '__main__':
+    app()

brolly/cli.py

@@ -0,0 +1,371 @@
+#!/usr/bin/env python3
+"""brolly — authenticate, repoint, or create AWS SSO profiles.
+
+usage:
+  brolly                             verify/refresh the current profile (same as `brolly refresh`)
+  brolly login [-s <session>]        force a fresh device-code login for a session
+  brolly switch                      pick a new account/role for $AWS_PROFILE (rewrites the profile in place)
+  brolly refresh [<profile>] [-s <session>]
+                                     cheaply verify/refresh a profile's credentials, logging in only if the
+                                     session is dead; defaults to $AWS_PROFILE
+  brolly add <profile> [-s <session>]
+                                     create a new profile under an existing sso-session, pick its account/role,
+                                     and leave it authenticated
+
+Bare `brolly` no longer force-logs-in — it refreshes the current profile; use `brolly login` for a forced login.
+
+-s/--session asserts which sso-session you are operating under (default: the current $AWS_PROFILE's).
+For refresh the target profile must actually belong to the asserted session, or the command fails loudly —
+crossing sessions is always deliberate.
+
+$AWS_PROFILE is never modified — it is the fixed handle; `switch` only changes what it resolves to, `add`
+creates a new profile without changing which one the shell uses, and `refresh` targets the aws CLI with
+--profile rather than touching the ambient env.
+"""
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+import termios
+import tty
+from typing import Any
+
+import boto3
+import botocore.session
+from botocore.exceptions import SSOTokenLoadError, TokenRetrievalError, UnauthorizedSSOTokenError
+from botocore.tokens import create_token_resolver
+
+type ProfileName = str
+type SessionName = str
+type Region = str
+type AccountId = str
+type RoleName = str
+type AccessToken = str
+type AwsConfig = dict[str, Any]  # botocore's full_config / scoped-config nested-dict shape
+type Account = dict[str, str]  # a boto3 sso.list_accounts entry: accountId, accountName, emailAddress
+
+_ORANGE = '\033[38;5;214m'
+_DIM = '\033[2m'
+_RESET = '\033[0m'
+
+# nerd-font glyphs (match the shell prompt's AWS pill)
+_AWS = ''  # amazon
+_ACCT = ''  # institution / account
+_ROLE = ''  # key / role
+_CURSOR = ''  # caret-right
+_CURRENT = ''  # check-circle
+_CHECK = ''  # check
+
+
+def _require_aws() -> None:
+    """Fail early with install guidance if the AWS CLI v2 is not on PATH — brolly shells out to `aws`."""
+    if shutil.which('aws') is None:
+        raise SystemExit(
+            'brolly needs the AWS CLI v2 (`aws`) on your PATH. Install it: '
+            'https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html'
+        )
+
+
+def _aws(*args: str, capture: bool = True) -> subprocess.CompletedProcess[str]:
+    """Run the aws CLI. capture=False lets an interactive command own the terminal (device-code login)."""
+    result = subprocess.run(['aws', *args], text=True, capture_output=capture)
+    if result.returncode != 0:
+        detail = (result.stderr or '').strip() if capture else ''
+        raise SystemExit(f'aws {" ".join(args)} failed{": " + detail if detail else ""}')
+    return result
+
+
+def _profile_sso(profile: ProfileName) -> tuple[SessionName, Region, AccountId | None, RoleName | None]:
+    """Return (session, region, account_id, role) for the profile; exit if it is not an SSO profile."""
+    session = botocore.session.Session(profile=profile)
+    cfg = session.get_scoped_config()
+    session_name: SessionName | None = cfg.get('sso_session')
+    if not session_name:
+        raise SystemExit(f"profile '{profile}' has no sso_session")
+    region: Region = session.full_config['sso_sessions'][session_name]['sso_region']
+    return session_name, region, cfg.get('sso_account_id'), cfg.get('sso_role_name')
+
+
+def _resolve_token(profile: ProfileName) -> AccessToken | None:
+    """A valid SSO access token — refreshed if the hourly one lapsed; None if the 7-day session is dead."""
+    resolver = create_token_resolver(botocore.session.Session(profile=profile))
+    try:
+        token = resolver.load_token()
+        return token.get_frozen_token().token if token is not None else None
+    except TokenRetrievalError, SSOTokenLoadError, UnauthorizedSSOTokenError:
+        return None
+
+
+def _ensure_token(profile: ProfileName, session_name: SessionName) -> AccessToken:
+    token = _resolve_token(profile)
+    if token is not None:
+        return token
+    # session fully expired (>7d): the refresh token is dead, so log in interactively, then resolve again
+    print(f"SSO session '{session_name}' expired — logging in…", file=sys.stderr)
+    _aws('sso', 'login', '--sso-session', session_name, '--no-browser', '--use-device-code', capture=False)
+    token = _resolve_token(profile)
+    if token is None:
+        raise SystemExit('could not obtain a valid SSO token after login')
+    return token
+
+
+def _read_key() -> str:
+    ch = sys.stdin.read(1)
+    if ch == '\x1b':
+        return {'[A': 'up', '[B': 'down'}.get(sys.stdin.read(2), 'esc')
+    if ch in ('\r', '\n'):
+        return 'enter'
+    if ch == '\x03':
+        return 'ctrl-c'
+    return ch
+
+
+def _render(rows: list[str], idx: int, current: int) -> None:
+    for i, row in enumerate(rows):
+        cursor = f'{_ORANGE}{_CURSOR}{_RESET}' if i == idx else ' '
+        dot = f'{_ORANGE}{_CURRENT}{_RESET}' if i == current else ' '
+        body = f'\033[7m {row} {_RESET}' if i == idx else f' {row} '
+        sys.stdout.write(f'\r\033[K  {cursor} {dot} {body}\n')
+
+
+def _menu(header: str, columns: list[str], rows: list[list[str]], default: int, current: int) -> int:
+    """Arrow-key selector over tabular rows; returns the chosen index. Falls back to numeric input off a TTY."""
+    widths = [max(len(columns[c]), *(len(r[c]) for r in rows)) for c in range(len(columns))]
+    lines = ['  '.join(cell.ljust(widths[c]) for c, cell in enumerate(row)) for row in rows]
+    head = '  '.join(col.ljust(widths[c]) for c, col in enumerate(columns))
+
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        print(f'\n{header}\n      {head}')
+        for i, line in enumerate(lines):
+            print(f'  {i + 1:>2}) {line}{"  ← current" if i == current else ""}')
+        while True:
+            try:
+                raw = input(f'select [1-{len(rows)}] (default {default + 1})> ').strip()
+            except EOFError:
+                raise SystemExit(130) from None
+            if not raw:
+                return default
+            if raw.isdigit() and 1 <= int(raw) <= len(rows):
+                return int(raw) - 1
+
+    idx = default
+    print(f'\n{header}   {_DIM}↑/↓ move · enter select · q quit{_RESET}')
+    print(f'      {_DIM}{head}{_RESET}')
+    _render(lines, idx, current)
+    fd = sys.stdin.fileno()
+    saved = termios.tcgetattr(fd)
+    sys.stdout.write('\033[?25l')
+    sys.stdout.flush()
+    try:
+        tty.setcbreak(fd)
+        while True:
+            key = _read_key()
+            if key in ('up', 'k'):
+                idx = (idx - 1) % len(rows)
+            elif key in ('down', 'j'):
+                idx = (idx + 1) % len(rows)
+            elif key == 'enter':
+                return idx
+            elif key in ('q', 'esc', 'ctrl-c'):
+                raise SystemExit(130)
+            else:
+                continue
+            sys.stdout.write(f'\033[{len(rows)}A')
+            _render(lines, idx, current)
+            sys.stdout.flush()
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+        sys.stdout.write('\033[?25h')
+        sys.stdout.flush()
+
+
+def cmd_login(session: SessionName) -> None:
+    _aws('sso', 'login', '--sso-session', session, '--no-browser', '--use-device-code', capture=False)
+
+
+def _pick_account_role(
+    sso_region: Region, token: AccessToken, cur_account: AccountId | None = None, cur_role: RoleName | None = None
+) -> tuple[Account, RoleName]:
+    """Interactively choose an account and role for the session; pre-selects cur_account/cur_role when given."""
+    sso = boto3.client('sso', region_name=sso_region)
+
+    accounts: list[Account] = []
+    for page in sso.get_paginator('list_accounts').paginate(accessToken=token):
+        accounts.extend(page['accountList'])
+    if not accounts:
+        raise SystemExit('no accounts available for this session')
+    accounts.sort(key=lambda a: a['accountName'])
+
+    acct_current = next((i for i, a in enumerate(accounts) if a['accountId'] == cur_account), -1)
+    rows = [[a['accountId'], a['accountName']] for a in accounts]
+    header = f'{_AWS}  {_ACCT}  select account'
+    account = accounts[_menu(header, ['ACCOUNT', 'NAME'], rows, max(acct_current, 0), acct_current)]
+    account_id: AccountId = account['accountId']
+
+    roles: list[RoleName] = []
+    for page in sso.get_paginator('list_account_roles').paginate(accessToken=token, accountId=account_id):
+        roles.extend(r['roleName'] for r in page['roleList'])
+    if not roles:
+        raise SystemExit(f'no roles available in {account_id}')
+    if len(roles) == 1:
+        role = roles[0]
+        print(f'{_ROLE}  only role: {role}')
+    else:
+        role_current = next((i for i, r in enumerate(roles) if r == cur_role and account_id == cur_account), -1)
+        header = f'{_AWS}  {_ROLE}  select role'
+        role = roles[_menu(header, ['ROLE'], [[r] for r in roles], max(role_current, 0), role_current)]
+    return account, role
+
+
+def _write_account_role(profile: ProfileName, account: Account, role: RoleName) -> None:
+    _aws('configure', 'set', 'sso_account_id', account['accountId'], '--profile', profile)
+    _aws('configure', 'set', 'sso_role_name', role, '--profile', profile)
+    _aws('configure', 'set', 'sso_account_name', account['accountName'], '--profile', profile)
+
+
+def cmd_switch(profile: ProfileName) -> None:
+    session_name, sso_region, cur_account, cur_role = _profile_sso(profile)
+    token = _ensure_token(profile, session_name)
+    account, role = _pick_account_role(sso_region, token, cur_account, cur_role)
+    account_id = account['accountId']
+    _write_account_role(profile, account, role)
+    print(f'\n{_ORANGE}{_CHECK}{_RESET}  {profile} → {account_id} ({account["accountName"]}) / {role}')
+
+
+def cmd_add(session: SessionName, new_profile: ProfileName, full_config: AwsConfig) -> None:
+    sso_sessions = full_config['sso_sessions']
+    profiles = full_config['profiles']
+
+    if session not in sso_sessions:
+        raise SystemExit(f"unknown sso-session '{session}' — available: {', '.join(sorted(sso_sessions))}")
+    if new_profile in profiles:
+        raise SystemExit(f"profile '{new_profile}' already exists — use `brolly switch` to repoint it")
+
+    sso_region: Region = sso_sessions[session]['sso_region']
+    sibling = next((p for p in profiles.values() if p.get('sso_session') == session), {})
+    _aws('configure', 'set', 'sso_session', session, '--profile', new_profile)
+    _aws('configure', 'set', 'region', sibling.get('region', sso_region), '--profile', new_profile)
+    _aws('configure', 'set', 'output', sibling.get('output', 'json'), '--profile', new_profile)
+
+    token = _ensure_token(new_profile, session)
+    account, role = _pick_account_role(sso_region, token)
+    account_id = account['accountId']
+    _write_account_role(new_profile, account, role)
+    print(f'\n{_ORANGE}{_CHECK}{_RESET}  added {new_profile} → {account_id} ({account["accountName"]}) / {role}')
+    print(f'{_DIM}  use it: export AWS_PROFILE={new_profile}{_RESET}')
+
+
+def _backfill_account_name(profile: ProfileName, sso_region: Region, account_id: AccountId | None) -> None:
+    if not account_id:
+        return
+    if botocore.session.Session(profile=profile).get_scoped_config().get('sso_account_name'):
+        return
+    token = _resolve_token(profile)
+    if token is None:
+        return
+    sso = boto3.client('sso', region_name=sso_region)
+    for page in sso.get_paginator('list_accounts').paginate(accessToken=token):
+        for a in page['accountList']:
+            if a['accountId'] == account_id:
+                _aws('configure', 'set', 'sso_account_name', a['accountName'], '--profile', profile)
+                return
+
+
+def cmd_refresh(target_profile: ProfileName, session: SessionName, full_config: AwsConfig) -> None:
+    profiles = full_config['profiles']
+    if target_profile not in profiles:
+        raise SystemExit(f"unknown profile '{target_profile}' — available: {', '.join(sorted(profiles))}")
+    actual: SessionName | None = profiles[target_profile].get('sso_session')
+    if not actual:
+        raise SystemExit(f"profile '{target_profile}' is not an SSO profile (no sso_session)")
+    if actual != session:
+        raise SystemExit(
+            f"profile '{target_profile}' is under session '{actual}', not '{session}' — use -s {actual} to target it"
+        )
+    if actual not in full_config['sso_sessions']:
+        raise SystemExit(f"sso-session '{actual}' referenced by '{target_profile}' is not defined")
+    sso_region: Region = full_config['sso_sessions'][actual]['sso_region']
+    account_id: AccountId | None = profiles[target_profile].get('sso_account_id')
+    check = subprocess.run(
+        ['aws', 'sts', 'get-caller-identity', '--profile', target_profile, '--query', 'Arn', '--output', 'text'],
+        text=True,
+        capture_output=True,
+    )
+    if check.returncode != 0:
+        print(f'{target_profile}: credentials unavailable — logging in…', file=sys.stderr)
+        _aws('sso', 'login', '--sso-session', actual, '--no-browser', '--use-device-code', capture=False)
+        arn = _aws(
+            'sts', 'get-caller-identity', '--profile', target_profile, '--query', 'Arn', '--output', 'text'
+        ).stdout.strip()
+    else:
+        arn = check.stdout.strip()
+    _backfill_account_name(target_profile, sso_region, account_id)
+    print(f'{_ORANGE}{_CHECK}{_RESET}  {target_profile} live → {arn}')
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog='brolly', description='authenticate, repoint, or create AWS SSO profiles')
+    sub = parser.add_subparsers(dest='cmd')
+
+    login = sub.add_parser('login', help='force a fresh device-code login for a session')
+    login.add_argument('-s', '--session', help="sso-session to log into (default: current profile's)")
+
+    sub.add_parser('switch', help='pick a new account/role for $AWS_PROFILE')
+
+    refresh = sub.add_parser('refresh', help="verify/refresh a profile's credentials")
+    refresh.add_argument('profile', nargs='?', help='target profile (default: $AWS_PROFILE)')
+    refresh.add_argument('-s', '--session', help="assert the sso-session (default: current profile's)")
+
+    add = sub.add_parser('add', help='create a new profile under an sso-session')
+    add.add_argument('profile', help='new profile name')
+    add.add_argument('-s', '--session', help="session to create it under (default: current profile's)")
+
+    return parser
+
+
+def _session_in_context(current: ProfileName, full_config: AwsConfig, override: SessionName | None) -> SessionName:
+    """The sso-session to operate under: an explicit -s override, else the current profile's; exit if neither."""
+    session = override or full_config['profiles'].get(current, {}).get('sso_session')
+    if not session:
+        raise SystemExit(
+            f"no sso-session in context — current profile '{current}' has no sso_session; pass -s <session>"
+        )
+    return session
+
+
+def main(argv: list[str]) -> None:
+    _require_aws()
+    current: ProfileName = os.environ.get('AWS_PROFILE', 'default')
+    parser = _build_parser()
+    args = parser.parse_args(argv or ['refresh'])
+    full_config: AwsConfig = botocore.session.Session().full_config
+    if args.cmd == 'login':
+        session = _session_in_context(current, full_config, args.session)
+        if session not in full_config['sso_sessions']:
+            raise SystemExit(
+                f"unknown sso-session '{session}' — available: {', '.join(sorted(full_config['sso_sessions']))}"
+            )
+        cmd_login(session)
+    elif args.cmd == 'switch':
+        cmd_switch(current)
+    elif args.cmd == 'refresh':
+        target = args.profile or current
+        cmd_refresh(target, _session_in_context(current, full_config, args.session), full_config)
+    elif args.cmd == 'add':
+        cmd_add(_session_in_context(current, full_config, args.session), args.profile, full_config)
+    else:
+        parser.print_usage(sys.stderr)
+        raise SystemExit(2)
+
+
+def app() -> None:
+    try:
+        main(sys.argv[1:])
+    except KeyboardInterrupt:
+        raise SystemExit(130) from None
+
+
+if __name__ == '__main__':
+    app()

brolly-0.1.0.dist-info/METADATA

@@ -0,0 +1,324 @@
+Metadata-Version: 2.3
+Name: brolly
+Version: 0.1.0
+Summary: A pure-Python CLI for AWS IAM Identity Center (SSO)
+Keywords: aws,sso,iam-identity-center,cli,boto3,aws-profile
+Author: Full Duplex Media
+Author-email: Full Duplex Media <contact@fullduplex.media>
+License: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
+Requires-Dist: boto3
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/fduplex/brolly
+Project-URL: Repository, https://github.com/fduplex/brolly
+Project-URL: Issues, https://github.com/fduplex/brolly/issues
+Description-Content-Type: text/markdown
+
+# brolly
+
+> *brolly* — British informal for umbrella. One login covers every profile under an AWS SSO session.
+
+A small, pure-Python CLI for AWS IAM Identity Center (SSO): log in once per session, switch accounts and roles
+in place, and keep your profiles fresh — without ever touching `$AWS_PROFILE`.
+
+brolly drives AWS SSO the way the modern `[sso-session]` config was meant to be used: authenticate once against
+a session and every profile that references it is usable. It refreshes and verifies credentials cheaply (the
+default), forces a fresh login when you want one, repoints the current profile to a different account/role, or
+adds a new profile under an existing session — and it ships a freshness-aware shell-prompt pill so you can see
+your credential state at a glance.
+
+```
+brolly                                  verify/refresh the current profile (same as `brolly refresh`)
+brolly login [-s <session>]             force a fresh device-code login for a session
+brolly switch                           repoint the current profile's account/role
+brolly refresh [<profile>] [-s <session>]
+brolly add <profile> [-s <session>]
+```
+
+## Install
+
+```console
+$ uv tool install brolly      # recommended
+$ pipx install brolly
+$ pip install brolly
+```
+
+**Prerequisites:**
+
+- **AWS CLI v2** on your `$PATH`. brolly shells out to `aws sso login` and `aws configure set`; everything else
+  (listing accounts/roles, resolving tokens) goes through boto3. The AWS CLI is *not* a pip dependency — install
+  it separately: <https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html>.
+- **Python 3.14+**.
+- **A Unix-like terminal.** The arrow-key picker uses `termios`/`tty`, so brolly's interactive menus need a
+  POSIX TTY (Linux, macOS, WSL). Off a TTY it falls back to numeric selection.
+
+## Mental model
+
+Modern AWS SSO config in `~/.aws/config` has two layers:
+
+- **`[sso-session <name>]`** — the session. Holds `sso_start_url`, `sso_region`, etc. Logging in against
+  a session caches ONE token, keyed by SHA1 of the session name (`~/.aws/sso/cache/<sha1>.json`).
+- **`[profile <name>]`** — a profile references a session via `sso_session = <name>` and adds its own
+  `sso_account_id` / `sso_role_name`. Any number of profiles can point at the same session.
+
+Because the token is cached per-session, not per-profile, **every profile under the same session shares one
+login** — authenticate once and all sibling profiles are usable. (One login covering many profiles is where the
+name comes from.)
+
+`$AWS_PROFILE` is a fixed handle you set yourself in each shell. **brolly never touches it** — it only changes
+what a profile resolves to (`switch`), creates new profiles (`add`), or verifies a profile's credentials
+(`refresh`, which targets the `aws` CLI with `--profile` rather than mutating the ambient env). To actually use
+a different profile you still `export AWS_PROFILE=<name>` yourself. There is no shell wrapper and nothing that
+rewrites your environment behind your back.
+
+## Commands
+
+### `brolly`
+
+Bare `brolly` (no subcommand) is shorthand for `brolly refresh` on the current `$AWS_PROFILE` — cheap, no
+browser unless the session is actually dead.
+
+```console
+$ brolly
+✔  corp-dev live → arn:aws:sts::111111111111:assumed-role/AdministratorAccess/alex
+```
+
+### `brolly login`
+
+Forces a fresh device-code login for an sso-session, unconditionally — no token check first. Session
+defaults to the current `$AWS_PROFILE`'s `sso_session`; `-s/--session` targets a different session. It's
+session-scoped, not profile-scoped (no profile argument).
+
+This is the rare escape hatch for "I'm still valid but I want a new login anyway" — `refresh` (and therefore
+bare `brolly`) already logs in automatically whenever a session is actually dead, so day to day you shouldn't
+need this.
+
+```console
+$ brolly login
+$ brolly login -s corp
+```
+
+### `brolly switch`
+
+Interactively repoints the CURRENT `$AWS_PROFILE` to a different account/role under its own session. Arrow-key
+picker (`↑`/`↓` or `j`/`k`, `enter` to select, `q`/`esc`/Ctrl-C to quit); shows the account list, then the role
+list (skipped if the account has exactly one role). Current account/role are pre-selected. `sso_account_id`,
+`sso_role_name`, and `sso_account_name` of that profile are rewritten in place — everything else about the
+profile is untouched. Recording `sso_account_name` is what lets the shell prompt show a friendly account name
+instead of the raw ID.
+
+```console
+$ export AWS_PROFILE=corp-prod
+$ brolly switch
+  select account   ↑/↓ move · enter select · q quit
+      ACCOUNT       NAME
+      111111111111  corp-prod       ← current
+    ▶ 222222222222  corp-staging
+
+  select role   ↑/↓ move · enter select · q quit
+      ROLE
+    ▶ AdministratorAccess
+
+✔  corp-prod → 222222222222 (corp-staging) / AdministratorAccess
+```
+
+### `brolly refresh`
+
+The cheap, no-browser daily-driver check. Takes an optional `<profile>` positional (default: `$AWS_PROFILE`)
+and an optional `-s/--session <name>` that asserts which sso-session you're operating in (default: the
+`sso_session` of the current `$AWS_PROFILE`). The target profile must actually belong to the asserted session,
+or the command fails loudly — this makes crossing sessions always deliberate:
+
+```console
+$ AWS_PROFILE=corp-dev brolly refresh corp-prod
+✔  corp-prod live → arn:aws:sts::222222222222:assumed-role/AdministratorAccess/alex
+
+$ AWS_PROFILE=customer-admin brolly refresh corp-prod
+profile 'corp-prod' is under session 'corp', not 'customer' — use -s corp to target it
+
+$ AWS_PROFILE=customer-admin brolly refresh corp-prod -s corp
+✔  corp-prod live → arn:aws:sts::222222222222:assumed-role/AdministratorAccess/alex
+```
+
+None of this ever touches `$AWS_PROFILE`: `refresh` runs `aws sts get-caller-identity --profile <target>` —
+overriding the ambient env var for just that one call — and logs in with `--sso-session <session>` if needed.
+Your shell's `$AWS_PROFILE` is exactly what it was before; that's the whole point of `-s` — it lets you check on
+(or log into) a profile in another session without poisoning your shell.
+
+Under the hood: `get-caller-identity` forces credential resolution and lets botocore refresh the hourly SSO
+token as a side effect — but only when the token is already lapsed or within ~15 min of expiry (botocore's own
+refresh window). If it still has plenty of time left, `refresh` just confirms you're authenticated without
+resetting the clock — that's the intended cheap behavior. Contrast with `brolly login`, which always does a full
+`aws sso login` unconditionally.
+
+If credentials can't be resolved at all (the 7-day session is dead), it prints a notice, falls through to a
+device-code `aws sso login`, and retries. It also opportunistically backfills `sso_account_name` on the target
+profile if that key is missing (one `list_accounts` call, made only when absent) — so an existing profile's
+prompt name heals itself the first time you refresh it.
+
+### `brolly add <profile> [-s <session>]`
+
+Creates a NEW profile under an existing sso-session, walks the same account/role picker, and leaves it
+authenticated and ready to use. `-s/--session` picks the session (default: the `sso_session` of the current
+`$AWS_PROFILE`) — there's no cross-session guard here like `refresh` has, since the profile being written is
+new:
+
+```console
+$ brolly add corp-qa                     # session inferred from current $AWS_PROFILE's sso_session
+$ brolly add customer-admin -s customer  # explicit session
+```
+
+What it does:
+
+1. Refuses if `<profile>` already exists (tells you to use `brolly switch` instead), or if `<session>` isn't a
+   known `sso-session` (lists the available ones).
+2. Writes a profile skeleton: `sso_session = <session>`, plus `region`/`output` copied from a sibling profile on
+   the same session if one exists, otherwise the session's `sso_region` and `json`.
+3. Ensures a valid token for the session, logging in if needed.
+4. Runs the account/role picker, then writes `sso_account_id` / `sso_role_name` / `sso_account_name`.
+
+It does **not** change `$AWS_PROFILE`. To use the new profile: `export AWS_PROFILE=<name>`.
+
+**Recovery:** if you Ctrl-C out of the picker mid-`add`, the profile skeleton (step 2) is already written to
+`~/.aws/config`, so re-running `brolly add` will hit the "already exists" guard. Finish it instead:
+
+```console
+$ export AWS_PROFILE=new-account
+$ brolly switch          # or `brolly` first if the token also expired
+```
+
+### Common tasks
+
+| Situation | Command |
+|---|---|
+| Verify/refresh current creds | `brolly` |
+| Force a fresh login (session healthy but you want a new one) | `brolly login` |
+| Wrong account or role for the current profile | `brolly switch` |
+| Need a new profile under the current session | `brolly add <name>` then `export AWS_PROFILE=<name>` |
+| Need a new profile under a different session, e.g. `customer` | `brolly add <name> -s customer` |
+| Refresh a profile in a different session from this shell | `brolly refresh <profile> -s <session>` |
+| Interrupted a `brolly add` mid-picker | `export AWS_PROFILE=<name>` then `brolly switch` |
+
+## Shell prompt integration
+
+brolly ships a drop-in `__aws_ps1` function for your `~/.bashrc` that renders a colored `AWS_PROFILE` pill
+reflecting the **local, filesystem-only** state of the session token — no network call, no `aws`/boto3
+invocation on every prompt:
+
+- **live** (bright orange) — hourly token still valid.
+- **idle** (grey, clock glyph) — cached but lapsed; refreshes automatically on next use.
+- **gone** (red, cross glyph) — no cached token; run `brolly`.
+- **plain** (neutral grey) — profile has no `sso_session` (not an SSO profile).
+
+A dead 7-day session can't be detected locally, so it still reads as `idle` rather than `gone`. The pill also
+shows the account: `<profile> · <account>`, where `<account>` is the friendly `sso_account_name` when the
+profile has one, falling back to the raw `sso_account_id` if not. Names get populated by `switch`, `add`, and
+`refresh`; until one of those runs against a given profile, the pill just falls back to the raw account ID.
+
+Drop this into your `~/.bashrc` and add `$(__aws_ps1)` to your `PS1`. It needs a **[Nerd Font](https://www.nerdfonts.com/)**
+for the powerline separators and glyphs.
+
+```bash
+__aws_ps1() {
+  [[ -z $AWS_PROFILE ]] && return
+
+  # Cheap, filesystem-only freshness check — no aws/boto3 call, no network.
+  # live = hourly token still valid · idle = cached but lapsed (refreshes on next use) · gone = no token, must log in.
+  # The 7-day session's true death can't be known locally, so a dead session reads as "idle", not "gone".
+  local cfg="${AWS_CONFIG_FILE:-$HOME/.aws/config}"
+  local session acct cache exp now state sbg sfg glyph
+  IFS=$'\t' read -r session acct < <(awk -v h="[profile $AWS_PROFILE]" '
+    $0==h {i=1; next}
+    /^\[/ {i=0}
+    i && /^[[:space:]]*sso_session[[:space:]]*=/      {v=$0; sub(/^[^=]*=[[:space:]]*/,"",v); s=v}
+    i && /^[[:space:]]*sso_account_name[[:space:]]*=/ {v=$0; sub(/^[^=]*=[[:space:]]*/,"",v); n=v}
+    i && /^[[:space:]]*sso_account_id[[:space:]]*=/   {v=$0; sub(/^[^=]*=[[:space:]]*/,"",v); a=v}
+    END {print s "\t" (n!=""?n:a)}' "$cfg" 2>/dev/null)
+
+  if [[ -z $session ]]; then
+    state=plain
+  else
+    cache="$HOME/.aws/sso/cache/$(printf %s "$session" | sha1sum | cut -c1-40).json"
+    if [[ ! -f $cache ]]; then
+      state=gone
+    else
+      exp=$(sed -n 's/.*"expiresAt"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$cache" | head -1)
+      printf -v now '%(%s)T' -1
+      exp=$(date -d "$exp" +%s 2>/dev/null)
+      [[ -n $exp && $exp -gt $now ]] && state=live || state=idle
+    fi
+  fi
+
+  case $state in
+    live)  sbg=214 sfg=236 glyph='' ;;         # bright AWS orange — creds are live
+    idle)  sbg=240 sfg=214 glyph=$' ' ;; #  grey clock — lapsed, will refresh on next use
+    gone)  sbg=160 sfg=231 glyph=$' ' ;; #  red cross — no cached token, run brolly
+    plain) sbg=238 sfg=250 glyph='' ;;         # non-SSO profile — neutral
+  esac
+
+  # powerline pill:  amazon-glyph | profile ; \001/\002 wrap non-printing bytes for correct prompt-width math
+  local E=$'\033' A=$'\001' B=$'\002' PL=$'' AWS=$''
+  printf '%s%s%s%s%s' \
+    "${A}${E}[48;5;238;38;5;214;1m${B} ${AWS} " \
+    "${A}${E}[38;5;238;48;5;${sbg}m${B}${PL}" \
+    "${A}${E}[48;5;${sbg};38;5;${sfg};1m${B} ${glyph}${AWS_PROFILE}${acct:+ · $acct} " \
+    "${A}${E}[0;38;5;${sbg}m${B}${PL}" \
+    "${A}${E}[0m${B} "
+}
+```
+
+## How it compares
+
+No single existing tool combines what brolly does. Its niche is the *combination*: native to the `sso-session` block
++ in-place `switch`/`add` + never mutating `$AWS_PROFILE` + a shipped freshness-aware prompt pill +
+pure-Python/pip.
+
+- **[aws-sso-util](https://github.com/benkehoe/aws-sso-util)** (Ben Kehoe) is the closest sibling — pure-Python,
+  config-native, and non-invasive, in the same spirit as brolly. But it has no prompt integration, no in-place
+  single-profile repoint, and predates the `sso-session` block.
+- **[granted](https://granted.dev/)** and **[aws-sso-cli](https://github.com/synfinatic/aws-sso-cli)** are
+  excellent tools, but they're Go binaries that install a shell wrapper mutating your shell and generate bulk
+  static profiles. brolly is deliberately thinner: no wrapper, no bulk generation, in-place edits only.
+- **[awsume](https://awsu.me/)** targets classic IAM role assumption, not Identity Center.
+
+This is positioning, not disparagement — if you want OS-keychain-encrypted tokens today, reach for aws-vault,
+granted, or aws-sso-cli (see caveats below and the roadmap).
+
+## Design notes & caveats
+
+Two things to own up front:
+
+- **`switch` rewrites `~/.aws/config` globally.** A profile lives in one shared config file, so switching the
+  account/role of a profile name silently retargets *any other shell* pinned to the **same profile name** on its
+  next command. Safe use = **one distinct profile name per concurrent context.** If you keep two shells on the
+  same account simultaneously, give them different profile names. This is the one real footgun — stated plainly.
+- **Tokens live in the stock plaintext `~/.aws/sso/cache/`** — the very same cache the `aws` CLI uses. brolly
+  adds no encryption of its own; it's a thin layer over the stock cache by design. For OS-keychain encryption
+  *today*, use aws-vault / granted / aws-sso-cli. Encrypted storage is the lead roadmap item below.
+
+## Roadmap
+
+1. **Keychain-backed token storage via a `credential_process` mode.** An opt-in mode where brolly does the
+   device auth itself, stores the SSO token in the OS keychain (via the Python
+   [`keyring`](https://github.com/jaraco/keyring) library), and registers itself as each profile's
+   `credential_process` — so credentials never sit in plaintext on disk and SDK consumers stay fully transparent
+   (just `AWS_PROFILE`, no shell wrapper). The prompt pill's freshness check would then read a small non-secret
+   expiry sidecar instead of the plaintext cache. On headless Linux with no OS keychain, `keyring` falls back to
+   an encrypted-file backend guarded by a passphrase. This mode makes brolly "take over credential resolution,"
+   which is exactly the trade the plaintext default avoids — so it stays **opt-in**, keeping brolly a thin stock-
+   cache layer by default.
+2. Test suite, CI, and publish to the `fduplex` PyPI org.
+
+## License
+
+[Apache-2.0](LICENSE) © 2026 Full Duplex Media

brolly-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+brolly/__init__.py,sha256=IMjkMO3twhQzluVTo8Z6rE7Eg-9U79_LGKMcsWLKBkY,22
+brolly/__main__.py,sha256=9Kc_V51Ueo2WBH-e1AaMNtMkuZhHX7SBEuTZH4S68oM,65
+brolly/cli.py,sha256=2tEhJ8DmBQNkumnGJEm_n2eHmct8fnfwOZHRQakPiCA,16679
+brolly-0.1.0.dist-info/WHEEL,sha256=r-Se0i_n47Mj8pdnVuq7W628oP9YAKMaTjp4l3lQcns,81
+brolly-0.1.0.dist-info/entry_points.txt,sha256=4YIDD2iDS-Ld0agrtxfQyzr9cRU4LoGxXZDBAIKaLPE,43
+brolly-0.1.0.dist-info/METADATA,sha256=ZYStTMAVzdD6MfEuk8qAQ32F6TXoYL9IOn6f3Y8ePYU,16579
+brolly-0.1.0.dist-info/RECORD,,

brolly-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.31
+Root-Is-Purelib: true
+Tag: py3-none-any

brolly-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+brolly = brolly.cli:app
+