GAM (gam-team/gam)

GAM

https://github.com/gam-team/gam
Admin
GAM is a command-line tool for Google Workspace administrators to efficiently manage domain and user...

Tokens:981,218
Snippets:7,492
Trust Score:7.2
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# GAM - Google Workspace Admin CLI

GAM (Google Apps Manager) is a free, open-source command line tool for Google Workspace administrators to manage domain and user settings quickly and easily. It provides comprehensive access to Google's Admin SDK APIs, enabling bulk operations on users, groups, organizational units, ChromeOS devices, calendars, Drive files, and many other Google Workspace resources. GAM simplifies complex administrative tasks that would otherwise require the web-based Admin Console or custom API development.

The tool supports both interactive and batch operations through CSV file processing, making it ideal for managing large Google Workspace environments. GAM requires an API project in Google Cloud Platform, authorization to act as a Google Workspace administrator, and optionally a service account for user-specific operations. The current version is GAM7 (v7.38.00), which offers enhanced functionality over Legacy GAM with support for additional APIs and improved performance through batch processing.

## Installation

GAM can be installed via an automated script or manually from releases.

```bash
# Linux/macOS/Google Cloud Shell - Automatic installation
bash <(curl -s -S -L https://git.io/gam-install)

# Install with custom path
bash <(curl -s -S -L https://git.io/gam-install) -d /custom/path

# Update existing installation
bash <(curl -s -S -L https://git.io/gam-install) -l

# Install via pip (requires Python)
pip install gam7
```

## User Management

Create, update, delete, and query users in your Google Workspace domain.

```bash
# Create a new user with password and notification
gam create user newuser@domain.com firstname "John" lastname "Doe" \
    password "SecurePass123" ou "/Employees" \
    notify helpdesk@domain.com

# Create user with random password and log to file
gam create user user@domain.com firstname "Jane" lastname "Smith" \
    password random ou "/Staff" logpassword ./passwords.txt

# Bulk create users from CSV file
# CSV format: useremail,firstname,lastname,ou,password,notifyemail
gam csv Users.csv gam create user "~useremail" \
    firstname "~firstname" lastname "~lastname" \
    ou "~ou" password "~password" notify "~notifyemail"

# Update user attributes
gam update user user@domain.com firstname "Jonathan" \
    phone type work value "555-1234" primary \
    organization name "Acme Corp" title "Engineer" department "IT" primary

# Update user password with notification
gam update user user@domain.com password "NewPassword456" \
    notify user@personal.com

# Suspend a user
gam suspend user user@domain.com

# Unsuspend a user
gam unsuspend user user@domain.com

# Delete a user
gam delete user user@domain.com

# Move user to different organizational unit
gam update user user@domain.com ou "/Former Employees"

# Display user information
gam info user user@domain.com

# Display user info with group membership and licenses
gam info user user@domain.com groups licenses

# Print all users to CSV
gam print users allfields > users.csv

# Print users in specific OU with selected fields
gam print users limittoou "/Students" fields primaryemail,name,ou,suspended

# Print suspended users
gam print users issuspended true

# Query users by criteria
gam print users query "orgUnitPath='/Sales'" fields primaryemail,name

# Count users in an OU
gam print users query "orgUnitPath='/Students/Middle School'" showitemcountonly
```

## Group Management

Create and manage Google Groups with membership and settings control.

```bash
# Create a new group
gam create group sales@domain.com name "Sales Team" description "Sales department group"

# Create group with specific access type
gam create group announce@domain.com name "Announcements" accesstype announcementonly

# Update group settings
gam update group sales@domain.com allowexternalmembers true \
    whocanpostmessage all_in_domain_can_post \
    whocanviewmembership all_in_domain_can_view

# Enable collaborative inbox
gam update group support@domain.com collaborative true

# Delete a group
gam delete group oldgroup@domain.com

# Display group information with members
gam info group sales@domain.com members managers owners

# Print all groups
gam print groups

# Print groups with settings
gam print groups allfields > groups.csv

# Print groups with member counts
gam print groups memberscount managerscount ownerscount totalcount

# Find groups with no members
gam config csv_output_row_filter "directMembersCount:count=0" print groups directmemberscount

# Query groups by name pattern
gam print groups query "name:test*" settings

# Show group and its parent groups (group tree)
gam show grouptree childgroup@domain.com
```

## Group Membership

Add, remove, and sync group members with role management.

```bash
# Add member to group
gam update group sales@domain.com add member user@domain.com

# Add member with specific role
gam update group sales@domain.com add owner manager@domain.com

# Add multiple members from CSV
# CSV format: email
gam csv members.csv gam update group sales@domain.com add member "~email"

# Remove member from group
gam update group sales@domain.com delete member user@domain.com

# Sync group membership with a list of users
gam update group sales@domain.com sync members file members.txt

# Print group members
gam print group-members group sales@domain.com

# Print all groups with their members
gam print groups members managers owners

# Print members with specific roles
gam print group-members group sales@domain.com roles owner,manager

# Update member role
gam update group sales@domain.com update owner user@domain.com
```

## Organizational Units

Create and manage organizational units for structuring your domain.

```bash
# Create organizational unit
gam create org "/Students/2024" description "Class of 2024"

# Create nested OU with buildpath (creates parent OUs if needed)
gam create org "/Departments/Engineering/Frontend" buildpath

# Update organizational unit
gam update org "/Students/2024" name "Graduates 2024" description "Graduated class of 2024"

# Delete organizational unit
gam delete org "/Old Department"

# Move users to organizational unit
gam update org "/Students/2024" add user user1@domain.com,user2@domain.com

# Move users from one OU to another
gam update org "/Students/2025" add ou_and_children "/Students/2024"

# Sync users with OU (add missing, remove extras)
gam update org "/Active Students" sync ou "/Enrolled Students" removetoou "/"

# Display OU information with users
gam info org "/Students"

# Print all organizational units
gam print orgs

# Print OU tree structure
gam print orgtree
```

## ChromeOS Device Management

Manage ChromeOS devices including updates, actions, and queries.

```bash
# Update device attributes
gam update cros dd1d659a-0ea4-4e94-905e-4726c7a5f1e9 \
    location "Building A, Room 101" \
    asset "CB-001" \
    user "student@domain.com" \
    notes "Assigned to 3rd grade classroom"

# Move device to new OU
gam cros_sn ABC123DEF456 update ou "/Classrooms/Room101" quickcrosmove

# Move multiple devices from one OU to another
gam cros_ou /Students/2021 update ou /Students/2022 quickcrosmove

# Bulk move devices from CSV
# CSV format: deviceId
gam update ou /Classrooms add croscsvfile devices.csv:deviceId quickcrosmove

# Disable a device
gam cros_sn ABC123DEF456 update action disable

# Deprovision a device (irreversible)
gam cros_sn ABC123DEF456 update action deprovision_retiring_device \
    acknowledge_device_touch_requirement

# Reenable a disabled device
gam cros_sn ABC123DEF456 update action reenable

# Remote wipe users from device
gam cros dd1d659a-0ea4-4e94-905e-4726c7a5f1e9 issuecommand command wipe_users doit

# Remote powerwash device
gam cros_sn ABC123DEF456 issuecommand command remote_powerwash \
    times_to_check_status 10 doit

# Display device information
gam info cros query:"id:ABC123DEF456"

# Print all ChromeOS devices
gam print cros

# Print devices with specific fields
gam print cros fields deviceId,serialNumber,status,lastSync,ou,annotatedUser

# Print devices not synced in 30 days
gam print cros query "sync:..#querytime1#" querytime1 -30d

# Print devices in specific OU
gam print cros cros_ou "/Classrooms"

# Print device activity (recent users and time ranges)
gam print crosactivity cros_ou "/Students" recentusers timeranges \
    listlimit 5 reverselists timeranges

# Count devices matching criteria
gam print cros query "sync:..2024-01-01" showitemcountonly

# Print device telemetry data
gam print crostelemetry ou "/Classrooms" fields serialnumber,cpuinfo,memoryinfo
```

## Calendar Management

Manage calendars, events, and access control lists.

```bash
# Display user's calendar list
gam user user@domain.com show calendars

# Add calendar to user's list
gam user user@domain.com add calendar teamcalendar@domain.com

# Create calendar event
gam user user@domain.com create event "Team Meeting" \
    start "2024-01-15 14:00" end "2024-01-15 15:00" \
    attendees "user1@domain.com,user2@domain.com" \
    location "Conference Room A" \
    description "Weekly team sync meeting"

# Share calendar with another user
gam user user@domain.com add calendaracl calendar primary \
    scope user:colleague@domain.com role reader

# Print calendar access control list
gam user user@domain.com print calendaracls

# Delete calendar event
gam user user@domain.com delete event id:<eventId>
```

## Drive File Management

Manage Google Drive files, permissions, and sharing.

```bash
# Display file information
gam user user@domain.com show fileinfo id:1234567890abcdef

# List files in user's Drive
gam user user@domain.com print filelist fields id,name,mimetype,owners

# Share file with another user
gam user user@domain.com add drivefileacl id:1234567890abcdef \
    user colleague@domain.com role writer

# Share file with domain
gam user user@domain.com add drivefileacl id:1234567890abcdef \
    domain domain.com role reader

# Remove file sharing
gam user user@domain.com delete drivefileacl id:1234567890abcdef id:permissionId

# Transfer file ownership
gam user oldowner@domain.com transfer drive newowner@domain.com

# Delete file
gam user user@domain.com delete drivefile id:1234567890abcdef

# Empty user's trash
gam user user@domain.com empty drivetrash

# Print all Drive files for users in OU
gam ou "/Employees" print filelist fields id,name,owners todrive
```

## Gmail Management

Manage Gmail settings, filters, delegates, and messages.

```bash
# Display Gmail profile
gam user user@domain.com show gmailprofile

# Create Gmail filter
gam user user@domain.com create filter \
    from "newsletter@example.com" \
    label "Newsletters" archive

# List Gmail filters
gam user user@domain.com print filters

# Delete Gmail filter
gam user user@domain.com delete filter id:<filterId>

# Add Gmail delegate
gam user executive@domain.com add delegate assistant@domain.com

# Remove Gmail delegate
gam user executive@domain.com delete delegate assistant@domain.com

# Print Gmail delegates
gam user user@domain.com print delegates

# Set vacation auto-reply
gam user user@domain.com vacation on subject "Out of Office" \
    message "I am currently out of the office and will respond upon my return."

# Turn off vacation auto-reply
gam user user@domain.com vacation off

# Update Gmail signature
gam user user@domain.com signature file signature.html

# Forward Gmail to another address
gam user user@domain.com forward on backup@personal.com archive
```

## Send Email

Send emails via Gmail API or SMTP.

```bash
# Send simple email
gam sendemail to user@domain.com subject "Important Notice" \
    message "This is the email body content."

# Send HTML email
gam sendemail to user@domain.com subject "Newsletter" \
    htmlmessage "<h1>Welcome</h1><p>This is HTML content.</p>"

# Send email from file
gam sendemail to user@domain.com subject "Report" \
    htmlfile ./email_template.html

# Send email with attachment
gam sendemail to user@domain.com subject "Documents" \
    message "Please find attached documents." \
    attach report.pdf attach data.xlsx

# Send email to multiple recipients
gam sendemail to "user1@domain.com,user2@domain.com,user3@domain.com" \
    subject "Team Update" message "Hello team..."

# Send email with CC and BCC
gam sendemail to user@domain.com cc manager@domain.com bcc hr@domain.com \
    subject "Performance Review" message "..."

# Send email with custom from address (using mailbox for API access)
gam sendemail from "IT Support <support@domain.com>" \
    mailbox admin@domain.com \
    to user@domain.com \
    subject "Support Request" message "Your ticket has been received."

# Send email as a user (service account access)
gam user sender@domain.com sendemail to recipient@domain.com \
    subject "Hello" message "Message from user"
```

## Reports and Audit

Generate usage reports and audit logs.

```bash
# Print admin audit log
gam report admin start 2024-01-01 end 2024-01-31

# Print login audit log
gam report login start 2024-01-01

# Print Drive audit log
gam report drive start 2024-01-01 user user@domain.com

# Print user usage report
gam report users date 2024-01-15 \
    fields accounts:last_login_time,accounts:gmail_used_quota_in_mb

# Print customer usage report
gam report customer date 2024-01-15

# Print specific application usage
gam report gmail start 2024-01-01 end 2024-01-31

# Export report to CSV
gam report admin start 2024-01-01 > admin_audit.csv
```

## Licenses

Manage Google Workspace licenses for users.

```bash
# Display user's licenses
gam user user@domain.com show licenses

# Assign license to user
gam user user@domain.com add license 1010020020

# Remove license from user
gam user user@domain.com delete license 1010020020

# Print all licenses
gam print licenses

# Print users with specific license
gam print users licenses sku 1010020020
```

## Bulk Operations with CSV

Process bulk operations using CSV files for large-scale management.

```bash
# Bulk create users from CSV
# CSV: primaryEmail,firstName,lastName,password,ou
gam csv users.csv gam create user "~primaryEmail" \
    firstname "~firstName" lastname "~lastName" \
    password "~password" ou "~ou"

# Bulk update users from CSV
gam csv updates.csv gam update user "~email" \
    phone type work value "~phone" primary

# Bulk add users to group from CSV
gam csv members.csv gam update group "~group" add member "~email"

# Bulk move devices from CSV
gam csv devices.csv gam cros "~deviceId" update ou "~ou"

# Parallel processing with multiprocess
gam config num_threads 10 redirect csv ./output.csv multiprocess \
    redirect stderr stdout csv ./input.csv gam user "~email" print filelist

# Redirect output to file
gam redirect csv ./users.csv print users allfields

# Redirect output to Google Drive
gam redirect csv - todrive print users allfields
```

## Configuration

Configure GAM settings and authentication.

```bash
# Show current configuration
gam info config

# Create new OAuth2 credentials
gam oauth create

# Update project APIs
gam update project

# Check service account authorization
gam user admin@domain.com check serviceaccount

# Set configuration values
gam config customer_id C01234567 domain domain.com timezone local save

# Verify configuration
gam config verify

# Show version information
gam version

# Check for updates
gam version checkrc
```

## Summary

GAM is the essential command-line tool for Google Workspace administrators who need to automate and scale their domain management tasks. It excels at bulk operations through CSV file processing, enabling administrators to create, update, and manage thousands of users, groups, and devices efficiently. The tool's comprehensive API coverage means virtually any administrative task that can be performed in the Admin Console can be automated with GAM, from user provisioning and license management to ChromeOS device deployment and audit log analysis.

Integration patterns typically involve combining GAM with shell scripts, scheduled tasks (cron jobs), or CI/CD pipelines for automated user lifecycle management. Common use cases include onboarding automation (creating users, adding to groups, assigning licenses), offboarding workflows (suspending users, transferring data, revoking access), ChromeOS device fleet management (moving devices between OUs, remote wiping, status reporting), and compliance reporting (generating audit logs, tracking license usage, monitoring login activity). GAM's output can be directed to CSV files or Google Drive for further processing with other tools, making it a cornerstone of Google Workspace automation infrastructure.