Metadata-Version: 2.4
Name: ssof
Version: 0.2.0
Summary: A simple CLI tool to manage AWS SSO sessions
Author-email: S Murali Krishnan <mrlikrsh@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mrlikl/ssof
Project-URL: Issues, https://github.com/mrlikl/ssof/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.3.0
Requires-Dist: boto3>=1.43.0
Requires-Dist: questionary>=2.1.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.0; extra == "dev"
Requires-Dist: black>=26.0.0; extra == "dev"
Dynamic: license-file

# ssof

Simple CLI tool to manage AWS SSO sessions across multiple organizations. Configure once per org, then just `ssof assume <account>` and you're in.

## Install

```bash
pip install ssof

# Enable shell completion (bash/zsh/fish)
eval "$(ssof completion bash)"   # add to ~/.bashrc
```

For local development:

```bash
uv sync
eval "$(uv run ssof completion bash)"   # add to ~/.bashrc
```

## Usage

```bash
# Configure an org
ssof config add my-org

# List cached accounts
ssof list

# Assume a role (interactive picker if no account given)
ssof assume my-account

# By account ID
ssof assume 123456789012

# With specific role
ssof assume my-account --role AdminRole

# Refresh cached accounts
ssof refresh

# Check current session status
ssof status
```

## Commands

| Command | Description |
|---------|-------------|
| `ssof config add <org>` | Add an SSO org configuration |
| `ssof config remove <org>` | Remove an SSO org |
| `ssof assume <account>` | Assume a role and configure AWS credentials |
| `ssof list` | List configured orgs and cached accounts |
| `ssof refresh` | Refresh cached accounts |
| `ssof status` | Check current credentials status |
| `ssof console` | Open AWS console in browser |
| `ssof logout` | Clear default AWS profile |

## Multi-Org

```bash
ssof config add company-prod
ssof config add company-dev
```

When multiple orgs are configured, `ssof assume` prompts for account selection across all of them.


## How it works

1. `ssof config add` stores your SSO start URL and region
2. Authenticates via browser and caches all accounts
3. `ssof assume` gets temporary credentials and writes to `~/.aws/credentials`
4. Backs up previous session automatically

Config stored in `~/.ssof/config.json`.

## Important: this tool modifies your AWS files

`ssof assume`, `ssof logout`, and switching to a backed-up profile write directly
to `~/.aws/credentials` and `~/.aws/config` using Python's `configparser`. That
means:

- **Comments and formatting in those files are not preserved.** If you
  hand-edit `~/.aws/credentials` or `~/.aws/config` (comments, blank lines,
  custom ordering), `configparser` will silently drop comments on the next
  write. The first time `ssof` ever writes to either file, it saves a pristine,
  untouched copy to `~/.ssof/backups/credentials.original` and
  `~/.ssof/backups/config.original` respectively (owner-readable only), so the
  original is always recoverable — but the live file itself will lose that
  formatting.
- **Profiles `ssof` doesn't touch are preserved.** Other `[profile]` sections
  in your credentials/config files are left alone.
- **`~/.aws/credentials` is kept at `chmod 600`** (owner read/write only) after
  every write, matching the AWS CLI's own convention for that file, since it
  holds long-lived or temporary secret keys.

## Requirements

- Python 3.10+
- boto3, click, questionary

## License

MIT — see [LICENSE](LICENSE).
