Brainforge Knowledge

GWS-GUIDE

5 min read

Google Workspace (gws) Onboarding Guide

This guide explains how to use gws (Google Workspace CLI) for onboarding new Brainforge team members.

Quick Start

1. Check gws Authentication

gws gmail users messages list --params '{"userId": "me", "maxResults": 1}'

If you get an authentication error, run:

gws auth login

2. Run Onboarding Script

cd knowledge/operations/onboarding
./onboard-new-hire-gws.sh "Davis Dunham" "rdavisdunham@gmail.com" "AI Engineer" "Engineering"

What gws Can Do for Onboarding

✅ Automated with gws:

  • Send welcome emails (Gmail)
  • Create calendar events for check-ins
  • Create onboarding Google Docs
  • Update spreadsheets (if you have access)
  • List files and share documents

❌ Requires Manual Action (gws doesn’t support Admin SDK):

  • Create Google Workspace users
  • Reset passwords
  • Manage user groups
  • Set user permissions

Full Onboarding Workflow with gws

Step 1: Authenticate gws

# Check if authenticated
gws gmail users messages list --params '{"userId": "me", "maxResults": 1}'
 
# If not authenticated:
gws auth login

Step 2: Create Google Workspace User (Manual)

gws doesn’t support user creation, so use Google Admin Console:

URL: https://admin.google.com
Path: Directory → Users → Add new user

Details:
- First name: Davis
- Last name: Dunham  
- Email: davis.dunham@brainforge.ai
- Send credentials to: rdavisdunham@gmail.com

Step 3: Send Welcome Email (Automated with gws)

# Using gws directly
gws gmail users messages send \
  --params '{"userId": "me"}' \
  --json '{
    "raw": "[base64 encoded email]"
  }'

Or use the onboarding script which handles this automatically.

Step 4: Create Calendar Events (Automated with gws)

# Week 1 check-in
gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{
    "summary": "Week 1 Check-in: Davis (New Hire)",
    "description": "1:1 with Department Lead and Uttam",
    "start": {"dateTime": "2026-04-29T10:00:00", "timeZone": "America/New_York"},
    "end": {"dateTime": "2026-04-29T11:00:00", "timeZone": "America/New_York"},
    "attendees": [{"email": "davis.dunham@brainforge.ai"}]
  }'

Step 5: Create Onboarding Document (Automated with gws)

# Create Google Doc
gws docs documents create \
  --json '{"title": "Davis Dunham - Onboarding Guide"}'
 
# Get document ID from output, then add content:
gws docs documents batchUpdate \
  --params '{"documentId": "DOC_ID"}' \
  --json '{
    "requests": [{
      "insertText": {
        "location": {"index": 1},
        "text": "Onboarding content here..."
      }
    }]
  }'

Step 6: Share Document (Automated with gws)

gws drive permissions create \
  --params '{"fileId": "DOC_ID"}' \
  --json '{
    "role": "writer",
    "type": "user",
    "emailAddress": "davis.dunham@brainforge.ai"
  }'

gws Command Reference for Onboarding

Gmail

Send welcome email:

gws gmail users messages send \
  --params '{"userId": "me"}' \
  --json '{
    "raw": "BASE64_ENCODED_EMAIL"
  }'

Check sent messages:

gws gmail users messages list \
  --params '{"userId": "me", "q": "to:davis.dunham@brainforge.ai"}'

Calendar

Create check-in event:

gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{
    "summary": "Week 1 Check-in: Davis",
    "description": "New hire check-in",
    "start": {"dateTime": "2026-04-29T10:00:00", "timeZone": "America/New_York"},
    "end": {"dateTime": "2026-04-29T11:00:00", "timeZone": "America/New_York"},
    "attendees": [{"email": "davis.dunham@brainforge.ai"}]
  }'

List events:

gws calendar events list \
  --params '{"calendarId": "primary", "q": "Davis"}'

Docs

Create onboarding document:

gws docs documents create \
  --json '{"title": "Davis Dunham - Onboarding Guide"}'

Update document:

gws docs documents batchUpdate \
  --params '{"documentId": "YOUR_DOC_ID"}' \
  --json '{
    "requests": [{
      "insertText": {
        "location": {"index": 1},
        "text": "Your content here"
      }
    }]
  }'

Drive

Share document:

gws drive permissions create \
  --params '{"fileId": "YOUR_DOC_ID"}' \
  --json '{
    "role": "writer",
    "type": "user",
    "emailAddress": "davis.dunham@brainforge.ai"
  }'

List files:

gws drive files list \
  --params '{"q": "name contains \"Davis\""}'

Sheets

Update Financial Model (if you have access):

gws sheets spreadsheets values append \
  --params '{
    "spreadsheetId": "SPREADSHEET_ID",
    "range": "Payroll Changes!A1",
    "valueInputOption": "USER_ENTERED"
  }' \
  --json '{
    "values": [["Davis Dunham", "2026-04-22", "Engineering", "AI Engineer", "Active"]]
  }'

Complete Onboarding Script

The onboard-new-hire-gws.sh script automates all gws-capable tasks:

./onboard-new-hire-gws.sh "Full Name" "personal@email.com" "Role" "Department"

What it does:

  1. ✅ Sends welcome email via Gmail
  2. ✅ Creates calendar events (Week 1, 30-day, 90-day check-ins)
  3. ✅ Creates onboarding Google Doc
  4. ✅ Shares doc with new hire
  5. ✅ Generates execution plan

What you do manually:

  1. ⏳ Create Google Workspace user (admin.google.com)
  2. ⏳ Add to Slack
  3. ⏳ Grant tool access (1Password, GitHub, etc.)
  4. ⏳ Add to HR Notion
  5. ⏳ Update Financial Model

Authentication Issues

”Authentication failed: invalid_grant”

Fix:

# Clear cached credentials
rm ~/.config/gws/credentials.enc
rm ~/.config/gws/token_cache.json
 
# Re-authenticate
gws auth login

“Server error: invalid_rapt”

Fix: Your token expired. Re-authenticate:

gws auth login

Check Current User

gws gmail users getProfile --params '{"userId": "me"}'

Best Practices

  1. Always authenticate first before running onboarding
  2. Test with your own email before sending to new hires
  3. Save execution plans for reference
  4. Use calendar events for check-ins (they auto-send invites)
  5. Create reusable templates for welcome emails

Troubleshooting

gws not found

# Install gws
npm install -g @googleworkspace/cli
 
# Or
brew install googleworkspace/tap/gws

Permission denied

You need to be logged in as a Google Workspace admin or have delegated access.

Rate limits

If you hit rate limits, add delays between commands:

sleep 1

Resources

Next Steps

For Davis Dunham:

  1. Authenticate gws:

    gws auth login

  2. Run onboarding script:

    cd knowledge/operations/onboarding
./onboard-new-hire-gws.sh "Davis Dunham" "rdavisdunham@gmail.com" "AI Engineer" "Engineering"

  3. Complete manual steps as prompted by the script:

    • Create Google Workspace user
    • Add to Slack
    • Grant tool access
    • Update documentation

Advanced: Customizing the Script

To modify what gws does, edit onboard-new-hire-gws.sh:

Change welcome email: Edit the WELCOME_SUBJECT and WELCOME_BODY variables.

Add more calendar events: Add new gws calendar events insert commands.

Customize onboarding doc: Edit the DOC_CONTENT variable.

Change check-in schedule: Modify the date calculations:

WEEK1_DATE=$(date -v+7d +%Y-%m-%d)  # Mac
WEEK1_DATE=$(date -d '+7 days' +%Y-%m-%d)  # Linux

Graph View

Backlinks