Metadata-Version: 2.4
Name: awsuser
Version: 0.1.0
Summary: CLI tool to authenticate AWS IAM users with password + MFA via Console sign-in (no access keys needed)
Project-URL: Homepage, https://github.com/tmb28054/awsuser
Project-URL: Repository, https://github.com/tmb28054/awsuser
Project-URL: Issues, https://github.com/tmb28054/awsuser/issues
Project-URL: Changelog, https://github.com/tmb28054/awsuser/blob/main/CHANGELOG.md
Author: Topaz Bott
License-Expression: MIT
License-File: LICENSE
Keywords: auth,aws,cli,user
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: keyring>=23.0
Requires-Dist: playwright>=1.40
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: pylint>=3.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# awsuser

Python CLI for AWS IAM user authentication with password + MFA. Automates the AWS Console sign-in flow using a headless browser to obtain temporary credentials — no pre-existing access keys needed.

## Installation

```bash
pip install awsuser
playwright install chromium
```

Or from source:

```bash
pip install -e ".[test]"
playwright install chromium
```

> **Note:** On macOS and Windows, `awsuser` uses your installed Google Chrome by default. You only need `playwright install chromium` if Chrome isn't installed or you want to use the bundled Chromium.

## Usage

```bash
# Basic usage (prompts for password and MFA code)
awsuser -a 123456789012 -u alice

# Save password to system keyring for next time
awsuser -a 123456789012 -u alice --save

# Output as environment variables
source <(awsuser -a 123456789012 -u alice --output env)

# Custom profile name
awsuser -a 123456789012 -u alice -p myprofile

# With specific region
awsuser -a 123456789012 -u alice --region us-west-2

# Use a specific browser
awsuser -a 123456789012 -u alice --browser firefox

# Debug mode (verbose logging)
awsuser -a 123456789012 -u alice --debug
```

## How It Works

1. Prompts for your IAM user password (or reads from keyring/`USER_PASSWORD` env var)
2. Prompts for your 6-digit MFA TOTP code
3. Opens a headless browser (Google Chrome on macOS/Windows, Chromium on Linux)
4. Automates the AWS Console sign-in flow (account + username + password + MFA)
5. Opens CloudShell and runs `aws configure export-credentials`
6. Extracts temporary credentials and writes them to `~/.aws/credentials`

## Running Tests

```bash
./run_tests.sh
```

Or manually:

```bash
python3 -m pytest tests/ --cov=awsuser --cov-report=term-missing --cov-fail-under=80 -v
```

## Documentation

- [User Guide](docs/user-guide.md)
- [FAQ](docs/faq.md)

## License

MIT

## Disclaimer

This tool automates the AWS Console sign-in flow using browser automation. It relies on the Console's UI structure which AWS may change without notice. If the tool stops working after an AWS Console update, please open an issue.
