Authentication

Configure authentication for AWS, GitHub, and Google to unlock full CLI functionality.

Overview

The CLI requires authentication with multiple services:

• AWS: Access secrets, deploy resources, query infrastructure
• GitHub: Create PRs, fetch code, manage repositories
• Google: Upload demo recordings, manage spreadsheets (optional)

All credentials are cached locally after initial setup for fast subsequent access.

AWS Authentication

Prerequisites

You must have access to the WS.Eng AWS account:

• Account name: RAM-AWS-Dev-WSEngineering-WSEng-Admin (profile: wsdev)
• Access method: AWS SAML via standardized tooling

If you don't have access, contact your engineering manager. See the AWS setup guide for details.

Setup AWS Profiles

The WS.Eng organization has 20+ AWS accounts. Engineers gain access to accounts gradually. The CLI can automatically configure all profiles you have access to:

wseng init --aws

What this does:

1. Uses standardized AWS SAML login tooling (saml2aws)
2. Discovers all AWS accounts you can access
3. Creates/updates AWS CLI profiles in ~/.aws/config
4. Populates profiles with correct role ARNs and settings

Result: You'll have profiles like these configured:

• tap - TeachTap production
• tapdev - TeachTap development
• wsdev - WS.Eng development (RAM-AWS-Dev-WSEngineering-WSEng-Admin)
• xo - Crossover accounts

Important: If your SAML2AWS credentials are incorrect, the CLI may hang indefinitely. If this happens, press Ctrl+C and see the AWS setup troubleshooting guide for credential verification steps.

Verify AWS Setup

Check that profiles are configured:

aws configure list-profiles

You should see profiles like tap, tapdev, wsdev, xo, etc.

How It Works

The CLI reads a large JSON blob from AWS Secrets Manager containing all service credentials (JIRA/GitHub tokens, API keys, etc.). This secrets file is:

• Cached locally after first fetch
• Automatically refreshed when expired
• Shared across all CLI commands

You don't manage individual secrets manually. The CLI handles it.

GitHub Authentication

Install and Login

The CLI uses GitHub CLI for repository operations:

# Install GitHub CLI (if not already installed)
# See: https://github.com/cli/cli/releases

# Login to GitHub
gh auth login

Follow the prompts to authenticate. Choose:

• Account: Your WS.Eng GitHub account
• Protocol: HTTPS or SSH (your preference)
• Authentication: Browser or token

Verify GitHub Auth

gh auth status

You should see "Logged in to github.com" with your username.

What Requires GitHub Auth

These CLI features depend on GitHub CLI authentication:

• Creating pull requests (wseng start-ticket)
• Fetching PR reviews (wseng fetch-pr-review)
• Repository operations (wseng ws clone-repositories)
• Release notes generation (wseng release-notes)

Google Authentication

Some CLI features interact with Google services (Drive, Sheets). Authentication is triggered automatically when needed.

When It's Required

• Demo recording: wseng record-demo uploads videos to Google Drive
• Spreadsheet sync: wseng sync-context-documents updates Google Sheets
• Analytics: Some data commands read/write Google Sheets

Setup

Run any command that needs Google access, or force authentication:

wseng init --google

The CLI will:

1. Open browser for Google OAuth
2. Request permissions for Drive and Sheets
3. Store refresh token locally

Configuration File Locations

After authentication, credentials are stored in:

~/.wseng                    # Personal CLI configuration
~/.aws/config               # AWS profiles
~/.aws/credentials          # AWS credentials (if using keys)
~/.config/gh/hosts.yml      # GitHub CLI tokens

These are cached and reused across CLI invocations. You don't re-authenticate every time.

Common Authentication Issues

"AWS credentials not found"

Re-run AWS setup and verify the profile exists:

wseng init --aws
aws configure list-profiles

Test that the profile works:

aws sts get-caller-identity --profile wsdev

"CLI hangs when running wseng init --aws"

This usually means your SAML2AWS credentials are incorrect. Press Ctrl+C to cancel, then see the AWS setup troubleshooting guide for credential verification steps.

"GitHub authentication failed"

Re-authenticate with GitHub CLI:

gh auth logout
gh auth login
gh auth status

"Access denied to AWS account"

You don't have permission for that AWS account yet. Contact your engineering manager to request access. Once granted, re-run wseng init --aws.

Related Docs

Configuration

Customize CLI behavior with .wseng configuration files.

Installation

Return to installation steps if authentication setup fails.

Ticket Lifecycle Workflow

Now that you're authenticated, start your first ticket workflow.