team-cli

A command-line interface for AWS TEAM (Temporary Elevated Access Management). Request, approve, and audit temporary elevated access to AWS accounts — without leaving the terminal.

Features

• Browser-based login via Cognito Hosted UI (OAuth2 + PKCE) with automatic token refresh
• Interactive and scriptable — use interactive prompts or pass flags for CI/automation
• Multi-account requests — select multiple accounts and submit requests in one go
• AWS config sync — auto-generate ~/.aws/config SSO profiles from your TEAM-eligible accounts
• Audit — query elevation requests with optional CloudTrail event correlation, with JSON output for piping

Requirements

• Python 3.11+
• A deployed AWS TEAM instance (AppSync API, Cognito user pool)

Installation

pip install .

Or install in editable/development mode:

pip install -e .

This makes the team command available in your shell.

Dependencies

Installed automatically:

Package	Purpose
requests	HTTP client for Cognito and AppSync APIs
InquirerPy	Interactive prompts (account/role selection, multi-select)

Configuration

Run the interactive setup wizard:

team configure

You'll be prompted for your TEAM deployment values:

Setting	Source
AppSync endpoint URL	Your TEAM CloudFormation stack outputs
Cognito domain	Cognito user pool → App integration → Domain name
Cognito client ID	Cognito user pool → App integration → App clients
Cognito user pool ID	Cognito user pool → General settings
Identity provider	Usually IDC (AWS Identity Center)
AWS region	The region your TEAM instance is deployed in

Configuration is stored at ~/.config/team-cli/config.toml with restrictive permissions (600). See config.example.toml for the full format.

View or edit config

team configure --show    # print current config
team configure --edit    # open in $EDITOR

Usage

Authentication

team login               # opens browser for Cognito/IDC login
team logout              # clears cached tokens

Tokens are cached locally and refreshed automatically. If a session expires mid-command, you'll be prompted to re-authenticate.

List eligible accounts and roles

team accounts            # show accounts you can request access to
team roles               # show available permission sets

Request elevated access

Interactive mode — multi-select accounts, pick a role, enter justification:

team request

Flag mode — for scripting or quick one-offs:

team request --account my-account --role ReadOnly --duration 2 --justification "Deploy hotfix" --ticket JIRA-123

Flag	Description
--account, -a	Account name or ID (partial match supported)
--role, -r	Permission set name or ID
--duration, -d	Duration in hours (default: 1)
--justification, -j	Business justification (required)
--ticket, -t	Ticket number
--start, -s	Start time in ISO format (default: now)
--wait, -w	Wait for request to reach a terminal state (for scripting)
--wait-timeout	Max seconds to wait (default: 600)

In interactive mode, you can select multiple accounts and reuse the same justification across them.

The --wait flag blocks until the request is approved, rejected, or otherwise resolved. Exit code 0 for approved/in-progress, 1 for rejected/error, 2 for timeout. When piped, outputs final request state as JSON.

Check request status

team requests            # list all your requests
team status <request-id> # detailed view of a single request
team pending             # list requests awaiting your approval

Approve, reject, revoke, cancel

team approve <request-id>                    # approve pending request
team approve <request-id> --comment "LGTM"   # with comment
team reject <request-id>                     # reject pending request
team reject <request-id> -c "Not justified"  # with reason
team revoke <request-id>                     # revoke active session
team revoke <request-id> -c "Security event" # with reason
team cancel <request-id>                     # cancel own pending request

Audit elevation requests

Query elevation history with optional CloudTrail event correlation. At least one filter is required.

team audit --actor user@example.com
team audit --account 123456789012 --from 2025-01-01 --to 2025-01-31
team audit --role AdministratorAccess --json
team audit --actor user@example.com --no-logs   # skip CloudTrail fetching

Flag	Description
--actor	Filter by requester email
--account	Filter by AWS account ID or name
--role	Filter by permission set name
--from	Start date (YYYY-MM-DD)
--to	End date (YYYY-MM-DD)
--status	Request status filter (default: ended)
--json	JSON output (auto-enabled when piped)
--no-logs	Skip CloudTrail event fetching
--limit	Max requests to process (default: 100)

JSON output is automatically enabled when stdout is not a TTY, making it easy to pipe into jq or other tools.

Sync AWS CLI profiles

Automatically generate ~/.aws/config SSO profiles for your TEAM-eligible accounts:

team sync

This requires SSO sync settings in your config. Run team configure and answer "yes" to the SSO sync prompt, or add a [sync] section to your config file:

[sync]
sso_session_name = "my-org"
sso_start_url = "https://my-org.awsapps.com/start"
sso_region = "us-east-1"
default_region = "us-east-1"

# Map TEAM permission set names to profile name suffixes
# Only listed permission sets generate profiles
[sync.profile_map]
ReadOnly = ""                    # my-account
AdministratorAccess = "-admin"   # my-account-admin

Accounts already present in ~/.aws/config (matched by sso_account_id) are skipped.

How it works

1. Authentication — team login runs an OAuth2 Authorization Code flow with PKCE. A local HTTP server on port 8484 captures the callback. Tokens (ID, access, refresh) are cached at ~/.config/team-cli/tokens.json with 600 permissions.

2. API — All TEAM operations go through the AppSync GraphQL API, authenticated with the Cognito ID token. Queries auto-paginate where applicable.

3. Sync — team sync reads your TEAM-eligible accounts and permissions, then writes matching SSO profiles into ~/.aws/config. It creates an sso-session block if missing and only adds profiles for permission sets listed in your profile_map.

Bash completions

Installed automatically via Homebrew. For non-Homebrew installs:

source /path/to/completions/team.bash

License

MIT/X Consortium (MIT). See LICENSE.