Skip to content

ACLabs-Code/google-admin-client

BranchesTags

Repository files navigation

gac - Google Admin Client

A powerful command-line tool for managing Google Workspace users, groups, calendars, and resources.

Go Version License

Overview

gac (Google Admin Client) is a CLI tool for automating Google Workspace administrative tasks. Built with Go, it provides a simple interface for managing users, groups, calendars, and more through the Google Admin SDK APIs.

Key Features

  • User Management - Create, list, update, suspend users
  • Group Management - Manage groups, memberships, and settings
  • Calendar Operations - Create and manage calendar events
  • Calendar Resources - Manage bookable resources (rooms, equipment)
  • Organizational Units - Manage organizational structure
  • Alias Management - Email aliases for users
  • Audit Log Export - Export audit logs for compliance and analysis
  • Performance Caching - Built-in caching for faster queries (30-90x speedup)
  • Shell Completion - Bash, zsh, and fish completion support
  • Config Validation - Validate configuration and credentials
  • Secure Authentication - OAuth2 with automatic token refresh
  • Cross-Platform - Linux and macOS (amd64 and arm64)

Quick Start

Installation

# macOS (Homebrew - coming soon)
# brew install acockrell/tap/gac

# Pre-built binaries
# Download from: https://github.com/acockrell/google-admin-client/releases

# macOS (Apple Silicon)
curl -LO https://github.com/acockrell/google-admin-client/releases/latest/download/gac_darwin_arm64.tar.gz
tar xzf gac_darwin_arm64.tar.gz
sudo mv gac /usr/local/bin/

# Linux (amd64)
curl -LO https://github.com/acockrell/google-admin-client/releases/latest/download/gac_linux_amd64.tar.gz
tar xzf gac_linux_amd64.tar.gz
sudo mv gac /usr/local/bin/

# Build from source
git clone https://github.com/acockrell/google-admin-client.git
cd google-admin-client
make build
sudo mv build/gac /usr/local/bin/

Authentication

  1. Set up OAuth2 credentials in Google Cloud Console

    • Create a project
    • Enable Admin SDK API and Calendar API
    • Create OAuth2 credentials (Desktop app)
    • Download the JSON file

  2. Configure credentials:

    mkdir -p ~/.credentials
mv ~/Downloads/client_secret_*.json ~/.credentials/client_secret.json
chmod 600 ~/.credentials/client_secret.json

  3. Authenticate:

    gac user list
# Follow the browser prompts to grant permissions

📖 Detailed setup: See Authentication Guide

Basic Usage

# List all users
gac user list

# Create a new user
gac user create john.doe@example.com

# Update user department
gac user update --dept Engineering john.doe@example.com

# View group settings
gac group-settings list team@example.com

# List calendar resources
gac cal-resource list --type room

Configuration

Configure gac via config file, environment variables, or CLI flags:

Config File (~/.google-admin.yaml)

domain: example.com
client-secret: /path/to/client_secret.json
cache-file: /path/to/token.json

Environment Variables

export GAC_DOMAIN=example.com
export GAC_CLIENT_SECRET=~/.credentials/client_secret.json
export GAC_CACHE_FILE=~/.credentials/gac.json

CLI Flags

gac --domain example.com user list

📖 Full configuration guide: docs/configuration.md

Logging and Debugging

Control log output for troubleshooting and monitoring:

# Enable verbose/debug logging
gac --verbose user list
gac -v user list

# Set specific log level (debug, info, warn, error)
gac --log-level debug user list

# JSON log output for automation/parsing
gac --json-log --log-level debug user list > debug.log

# Combine with other flags
gac -v --domain example.com user suspend user@example.com

Log Levels:

  • debug - Detailed API calls, requests, and responses
  • info - General operational messages (default)
  • warn - Warning messages (insecure permissions, deprecations)
  • error - Error messages only

Use Cases:

  • Troubleshooting - Use -v or --log-level debug to see API calls and diagnose issues
  • Automation - Use --json-log for structured logs that can be parsed by log aggregators
  • Production - Use --log-level warn or --log-level error to reduce noise

Common Tasks

User Management

# Create user with groups
gac user create \
  --first-name John \
  --last-name Doe \
  --groups engineering \
  --groups all-staff \
  john.doe@example.com

# Suspend user
gac user suspend user@example.com --reason "Left company"

# Unsuspend user
gac user unsuspend user@example.com

📖 Full guide: User Management

Group Settings

# Configure moderated announcements group
gac group-settings update announcements@example.com \
  --who-can-post-message ALL_MANAGERS_CAN_POST \
  --message-moderation-level MODERATE_ALL_MESSAGES \
  --allow-external-members false

# Add custom footer
gac group-settings update support@example.com \
  --custom-footer-text "For help, contact support@example.com" \
  --include-custom-footer true

📖 Full guide: Group Settings

Calendar Resources

# Create conference room
gac cal-resource create conf-room-a \
  --name "Conference Room A" \
  --type room \
  --capacity 12 \
  --building-id main-building

# List all rooms
gac cal-resource list --type room

📖 Full guide: Calendar Resources

Organizational Units

# Create OU
gac ou create /Engineering/Backend

# List OUs
gac ou list

# Move user to OU
gac user update --ou /Engineering/Backend user@example.com

📖 Full guide: Organizational Units

Audit Log Export

# Export last 24h of admin console activities
gac audit export --app admin

# Export login activities for specific user
gac audit export --app login --user user@example.com

# Export drive activities to CSV
gac audit export --app drive \
  --start-time 2024-10-01T00:00:00Z \
  --end-time 2024-10-08T00:00:00Z \
  --output csv --output-file drive-audit.csv

# Filter by event types
gac audit export --app admin --event-name USER_CREATED

📖 Full guide: Audit Logs

Performance and Caching

Speed up repeated queries with built-in caching:

# First call - fetches from API (~1200ms)
gac user list

# Subsequent calls - uses cache (~35ms) - 34x faster!
gac user list

# View cache statistics
gac cache status

# Clear cache when needed
gac cache clear users
gac cache clear groups
gac cache clear all

# Disable cache for fresh data
gac user list --no-cache

# Configure cache TTL
gac user list --cache-ttl 30m

Benefits:

  • 30-90x faster queries with caching enabled
  • 80-90% reduction in API quota usage
  • Automatic cache expiration (default: 15 minutes)
  • Configurable cache location and TTL

Configuration (~/.google-admin.yaml):

cache:
  enabled: true
  ttl: 15m
  directory: ~/.cache/gac

📖 Full guide: Caching

CLI Utilities

# Show version information
gac version

# Show version number only
gac version --short

# Validate configuration
gac config validate

# Generate shell completion
gac completion bash > /etc/bash_completion.d/gac  # Linux
gac completion zsh > ~/.oh-my-zsh/completions/_gac  # zsh
gac completion fish > ~/.config/fish/completions/gac.fish  # fish

# Skip confirmations for automation (use with caution)
gac user suspend user@example.com --yes
gac ou delete /OldOU -y

📖 Shell completion guide: Shell Completion

Documentation

📚 User Guides

📖 Reference

🔧 Configuration & Setup

💻 Development

📝 Examples

Command Reference

Category Commands
Users create, list, update, suspend, unsuspend
Groups list
Group Settings list, update
Calendar create, list, update
Calendar Resources list, create, update, delete
Organizational Units list, create, update, delete
Aliases list, add, remove
Audit export
Data Transfer transfer

📖 Full command reference: docs/reference/commands.md

Troubleshooting

Common Issues

Authentication errors

# Delete cached token and re-authenticate
rm ~/.credentials/gac.json
gac user list

Permission errors

  • Verify you have Google Workspace admin privileges
  • Check OAuth scopes in docs/authentication.md
  • Ensure required APIs are enabled in Google Cloud Console

Domain configuration

# Set domain via environment variable
export GAC_DOMAIN=example.com
gac user list

📖 Full troubleshooting guide: docs/reference/troubleshooting.md

Contributing

We welcome contributions! See CONTRIBUTING.md for:

  • Reporting bugs
  • Suggesting features
  • Submitting pull requests
  • Development setup

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with:

Links

Made with ❤️ for Google Workspace administrators

About

Golang CLI to manage Google Workspaces via the Google Admin API

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages