feat(admin): add user and group management (Admin Directory API)

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 0.12.0 - Unreleased
 
 ### Added
+- Admin: add Workspace Admin Directory commands for users and groups, including user list/get/create/suspend and group membership list/add/remove. (#403) — thanks @dl-alexandre.
 - Sheets: add named range management (`sheets named-ranges`) and let range-based Sheets commands accept named range names where GridRange-backed operations are needed. (#278) — thanks @TheCrazyLex.
 - Docs: add `--pageless` to `docs create`, `docs write`, and `docs update` to switch documents into pageless mode after writes. (#300) — thanks @shohei-majima.
 - Contacts: add `--relation type=person` to contact create/update, include relations in text `contacts get`, and cover relation payload updates. (#351) — thanks @karbassi.

README.md

@@ -1105,6 +1105,21 @@ gog chat dm send user@company.com --text "ping"
 
 Note: Chat commands require a Google Workspace account (consumer @gmail.com accounts are not supported).
 
+### Admin
+
+```bash
+# Requires a Workspace service account with domain-wide delegation.
+gog admin users list --domain example.com
+gog admin users get user@example.com
+gog admin users create user@example.com --given Ada --family Lovelace --password 'TempPass123!'
+gog admin users suspend user@example.com --force
+
+gog admin groups list --domain example.com
+gog admin groups members list engineering@example.com
+gog admin groups members add engineering@example.com user@example.com --role MEMBER
+gog admin groups members remove engineering@example.com user@example.com --force
+```
+
 ### Groups (Google Workspace)
 
 ```bash

internal/cmd/admin.go

@@ -0,0 +1,8 @@
+package cmd
+
+// AdminCmd provides Google Workspace admin commands using the Admin SDK Directory API.
+// Requires domain-wide delegation with a service account.
+type AdminCmd struct {
+	Users  AdminUsersCmd  `cmd:"" name:"users" help:"Manage Workspace users"`
+	Groups AdminGroupsCmd `cmd:"" name:"groups" help:"Manage Workspace groups"`
+}

internal/cmd/admin_common.go

@@ -0,0 +1,52 @@
+package cmd
+
+import (
+	"strings"
+
+	"github.com/steipete/gogcli/internal/errfmt"
+	"github.com/steipete/gogcli/internal/googleapi"
+)
+
+var newAdminDirectoryService = googleapi.NewAdminDirectory
+
+const (
+	adminRoleMember  = "MEMBER"
+	adminRoleOwner   = "OWNER"
+	adminRoleManager = "MANAGER"
+)
+
+func requireAdminAccount(flags *RootFlags) (string, error) {
+	account, err := requireAccount(flags)
+	if err != nil {
+		return "", err
+	}
+	if isConsumerAccount(account) {
+		return "", errfmt.NewUserFacingError(
+			"Admin SDK Directory API requires a Google Workspace account with domain-wide delegation; consumer accounts (gmail.com/googlemail.com) are not supported.",
+			nil,
+		)
+	}
+	return account, nil
+}
+
+// wrapAdminDirectoryError provides helpful error messages for common Admin SDK issues.
+func wrapAdminDirectoryError(err error, account string) error {
+	errStr := err.Error()
+	if strings.Contains(errStr, "accessNotConfigured") ||
+		strings.Contains(errStr, "Admin SDK API has not been used") {
+		return errfmt.NewUserFacingError("Admin SDK API is not enabled; enable it at: https://console.developers.google.com/apis/api/admin.googleapis.com/overview", err)
+	}
+	if strings.Contains(errStr, "insufficientPermissions") ||
+		strings.Contains(errStr, "insufficient authentication scopes") ||
+		strings.Contains(errStr, "Not Authorized") {
+		return errfmt.NewUserFacingError("Insufficient permissions for Admin SDK API; ensure your service account has domain-wide delegation enabled with admin.directory.user, admin.directory.group, and admin.directory.group.member scopes", err)
+	}
+	if strings.Contains(errStr, "domain_wide_delegation") ||
+		strings.Contains(errStr, "invalid_grant") {
+		return errfmt.NewUserFacingError("Domain-wide delegation not configured or invalid; ensure your service account has domain-wide delegation enabled in Google Workspace Admin Console", err)
+	}
+	if isConsumerAccount(account) {
+		return errfmt.NewUserFacingError("Admin SDK Directory API requires a Google Workspace account with domain-wide delegation; consumer accounts (gmail.com/googlemail.com) are not supported.", err)
+	}
+	return err
+}