gsuite-manager 0.3.0

CLI tool for automating Google Workspace + Cloudflare domain & user management

gsuite-manager (gsm)

Automate Google Workspace + Cloudflare in one CLI.
Onboard domains, create users, manage DNS — idempotent, tested, production-ready.

Documentation • Contributing • Discussions

---

Why gsuite-manager?

	Manual (Admin Console + CF Dashboard)	gsuite-manager
Onboard 10 domains	~2 hours clicking	gsm domains add --file domains.txt → 3 min
Create 50 users	Copy-paste hell	gsm users gen --count 50 --apply → 30 sec
Audit DNS health	Check each domain manually	gsm health → instant report
Rotate credentials	Remember where everything is	gsm setup → guided wizard

No SDK to learn. No YAML to write. No API docs to read. Just gsm and pick a number.

Features

Feature	Description
Domain onboarding	Add to Workspace → CF zone → DNS inject → verify (7-step pipeline, idempotent)
Auto-disable Email Routing	Detects CF Email Routing conflict, disables before MX inject
DNS propagation fix	Polls 8.8.8.8 + 1.1.1.1 before verify (eliminates race failures)
User management	Create, delete, suspend, reset password, aliases, groups, OU move
Auto-generate users	Faker-based, locale-aware, collision-safe, with license assignment
Audit & monitoring	CF vs Workspace gap, DNS health, domain expiry alerts
Interactive menu	Just type gsm, pick a number. No commands to memorize
Progress bar + ETA	Real-time progress for batch operations
Retry with backoff	CF API calls retry 3x on transient failures
Friendly errors	Technical errors translated to actionable hints

Quick Start

git clone https://github.com/nopperabbo/gsuite-manager.git
cd gsuite-manager
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
gsm setup    # interactive wizard
gsm doctor   # verify 5/5 PASS
gsm          # open menu

Windows / Linux notes

OS	Activate venv
macOS / Linux	source .venv/bin/activate
Windows CMD	.venv\Scripts\activate.bat
Windows PowerShell	.venv\Scripts\Activate.ps1

macOS Python 3.14: Run chflags -R nohidden .venv after install.

Linux: If venv missing: sudo apt install python3-venv

Examples

# Onboard domains (auto: Workspace + CF + DNS + verify)
gsm domains add --file domains.txt

# Auto-generate 50 users with Education license
gsm users gen --domain school.tech --count 50 --license education --apply

# Audit: what's in CF but not in Workspace?
gsm audit --output gaps.txt

# Reset all passwords in a domain
gsm users reset-password --domain old.tech --random --output new-creds.txt

# One command does everything (auto-detect files in CWD)
gsm go

Prerequisites

• Python 3.11+
• Google Workspace admin account
• Cloudflare account with domains as zones
• Google OAuth Desktop App credentials
• Cloudflare API Token (template: "Edit zone DNS")

[!NOTE] You only need Cloudflare for domain features. User management works with just Google Workspace.

Documentation

Doc	Description
Usage Guide (English)	Complete command reference
Tutorial (Bahasa Indonesia)	Full usage guide
How to Test	Tier 1 smoke + Tier 2 real test
Google OAuth Setup	Get credentials.json step-by-step
CF Token Rotation	3-minute token refresh
Production Runbook	Pre-production checklist
Roadmap	Future phases
Changelog	Release history
Contributing	Dev setup & guidelines

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        CLI Layer                             │
│  gsm menu │ gsm go │ gsm domains │ gsm users │ gsm groups  │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                    Workflow Layer                            │
│  domain_onboarding (7-step) │ user_bulk_create │ dns_apply  │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                    Client Layer                              │
│  Cloudflare API │ Google Admin SDK │ Google Verify │ DNS     │
│  (retry+backoff)│ (users/domains)  │ (site verify) │(dnspy) │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                     Core Layer                               │
│  config (pydantic) │ auth (OAuth2) │ errors │ logging       │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                   State Layer                                │
│  JSON Ledger (atomic writes, corrupt recovery, archive)     │
└─────────────────────────────────────────────────────────────┘

src/gsm/
├── cli/         # Typer commands + interactive menu
├── clients/     # CF, Google Admin, Google Verify, DNS, Faker
├── core/        # Config, OAuth, logging, error humanizer
├── models/      # Pydantic schemas (domain, user, results)
├── state/       # JSON ledger (atomic writes, corrupt recovery)
└── workflows/   # Domain onboarding, user creation orchestration

FAQ

Is this safe for production?

Yes. All operations are idempotent (safe to re-run), use atomic writes for state, and include dry-run mode. The tool has 90%+ test coverage with strict type checking.

Does it work on Windows?

Yes. CI runs on Ubuntu, macOS, and Windows. Use PowerShell for activation: .venv\Scripts\Activate.ps1

Can I use this without Cloudflare?

Partially. User management commands (gsm users *, gsm groups *) work with just Google Workspace. Domain onboarding and DNS features require Cloudflare.

How do I pronounce "gsm"?

"gee-ess-em" — the CLI command. The full project name is "gsuite-manager" (gee-suite manager).

What Google API scopes are required?

Only 3 scopes: admin.directory.user, admin.directory.group, admin.directory.domain — minimized for security.

License

MIT © nopperabbo