If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/openclaw/gogcli shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 7 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 92% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live openclaw/gogcli repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/openclaw/gogcli.

What it runs against: a local clone of openclaw/gogcli — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in openclaw/gogcli | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of openclaw/gogcli. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/openclaw/gogcli.git
#   cd gogcli
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of openclaw/gogcli and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "openclaw/gogcli(\\.git)?\\b" \\
  && ok "origin remote is openclaw/gogcli" \\
  || miss "origin remote is not openclaw/gogcli (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/gog/main.go" \\
  && ok "cmd/gog/main.go" \\
  || miss "missing critical file: cmd/gog/main.go"
test -f ".golangci.yml" \\
  && ok ".golangci.yml" \\
  || miss "missing critical file: .golangci.yml"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/openclaw/gogcli"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

gogcli is a script-friendly Go CLI for programmatic access to Google Workspace APIs (Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Contacts, Tasks, People, Classroom, Chat, and Admin Directory). It provides predictable JSON/plain-text output optimized for shell scripts, CI pipelines, and AI coding agents—solving the problem of parsing Google's official SDKs which are designed for application code, not automation. Monorepo structure: cmd/gog/ contains the main CLI entry point (uses alecthomas/kong for command parsing), cmd/bake-safety-profile/ generates restricted binaries, internal/ packages (inferred) wrap Google APIs, .agents/skills/gog/ provides integration for agent frameworks. GitHub Actions workflows automate multi-platform releases (windows, darwin, linux).

DevOps engineers, SREs, and AI agents building automation over Google Workspace; system administrators managing Workspace domains; shell script developers needing Google API access without writing Go; CI/CD pipelines requiring Gmail, Calendar, or Drive integration.

Active and production-ready: ~4.8MB Go codebase with release automation (.goreleaser.yaml), Docker builds (ghcr.io registry), Homebrew distribution, comprehensive CI via GitHub Actions (ci.yml, release.yml, docker.yml), and generated command documentation. The codebase is well-structured with safety-profile binaries and command allowlists/denylists for secure automation.

Low-to-medium risk: single maintainer (steipete) visible in repo structure; 20+ direct dependencies (google.golang.org/api, x/oauth2, keyring backends) introducing supply-chain surface; OAuth token refresh expiration quirks for External+Testing apps noted in README; no visible open issue count in provided data, but Google API versioning changes could require maintenance.

Active development: Go 1.26.2 support, recent dependency updates (google.golang.org/api v0.277.0, x/oauth2 v0.36.0), Docker image publishing, Homebrew distribution pipeline, and agent/AI integration (AGENTS.md file suggests recent feature expansion). Lefthook pre-commit hooks and actionlint suggest CI enforcement is being strengthened.

git clone https://github.com/steipete/gogcli.git
cd gogcli
make
./bin/gog --version

Then authenticate: gog auth credentials ~/Downloads/client_secret_....json && gog auth add you@gmail.com --services gmail,calendar,drive

Daily commands:

make                    # Build binary to ./bin/gog
make test              # Run tests
make fmt               # Run gofmt
./bin/gog --help       # Show CLI structure
export GOG_ACCOUNT=you@gmail.com
./bin/gog gmail search 'newer_than:7d' --max 10 --json

Or Docker: docker run --rm ghcr.io/steipete/gogcli:latest version

• cmd/gog/main.go — Entry point for the CLI—parses commands, initializes auth, and orchestrates all service calls; every feature flows through here
• .golangci.yml — Linter configuration enforcing code quality; violations block CI and must be understood before submitting changes
• go.mod — Module dependencies including google.golang.org/api, oauth2, and keyring; any dependency version bump affects all features
• Makefile — Build, test, and release workflows; contributors must follow these targets to ensure consistent builds
• .github/workflows/ci.yml — Continuous integration pipeline—defines test and lint steps that gate all merges
• docs/commands.generated.md — Auto-generated command reference; indicates the codebase regenerates docs on every build—commands must be kept in sync
• PR_DESCRIPTION.md — Template and guidelines for PRs; establishes review expectations and contribution standards

Add a New Google Service Command (e.g., Sheets API call)

1. Define command struct with kong tags in cmd/gog/main.go, following existing patterns for flags, aliases, and JSON output (cmd/gog/main.go)
2. Call google.golang.org/api service client in the command handler, catching errors and returning structured responses (cmd/gog/main.go)
3. Write unit tests in cmd/gog/main_test.go to validate flag parsing and OAuth client initialization (cmd/gog/main_test.go)
4. Add command documentation by running make generate-docs to auto-generate docs/commands/gog-<service>-<action>.md (docs/commands.generated.md)
5. Update README.md with brief description of the new command and its use case (README.md)

Restrict Commands via Safety Profile

1. Create allowlist or denylist in build-safe.sh specifying which commands are permitted (build-safe.sh)
2. Run bake-safety-profile tool to generate a locked-down binary with restricted command set (cmd/bake-safety-profile/main.go)
3. Test the safety profile using tests in cmd/bake-safety-profile/main_test.go (cmd/bake-safety-profile/main_test.go)
4. Distribute the baked binary instead of the unrestricted version for sensitive environments (Dockerfile)

Add Multi-Account OAuth Support

1. Reference .env.example to understand keyring backend, password, and service account variables (.env.example)
2. Extend cmd/gog/main.go to parse --account flag and load credentials from selected account (cmd/gog/main.go)
3. Consult docs/auth-clients.md for OAuth client setup and token refresh logic (docs/auth-clients.md)
4. Add integration tests in cmd/gog/main_test.go covering account switching and token expiry (cmd/gog/main_test.go)

Enable Agent Automation

1. Review AGENTS.md to understand how agents invoke gogcli and parse structured JSON output (AGENTS.md)
2. Ensure your new commands emit --json output from cmd/gog/main.go for agent consumption (cmd/gog/main.go)
3. Define agent skill in .agents/skills/gog/SKILL.md describing command semantics and output schema (.agents/skills/gog/SKILL.md)
4. Test agent invocation end-to-end via Docker or local binary (Dockerfile)

• Go 1.26+ — Cross-platform compilation, single binary distribution, native OAuth2 and gRPC support via google.golang.org/api
• kong CLI framework — Declarative command routing and flag parsing; auto-generates help and supports structured output
• google.golang.org/api — Official Google API client library; covers Gmail, Calendar, Drive, Sheets, Contacts, and admin APIs in a single dependency
• 99designs/keyring — Secure multi-backend credential storage (OS keychain, encrypted file); enables multi-account workflows without plaintext tokens
• filippo.io/age — Modern age encryption for encrypted file keyring backend; avoids deprecated crypto libraries
• Docker + Homebrew — Packaging and distribution for both container and native environments; CI/CD gates ensure reproducible builds

• Single monolithic CLI vs. service daemon

  • Why: Script-friendly execution model: stdout/stderr are predictable, no long-running server state, easy to invoke from cron or CI
  • Consequence: Each invocation re-authenticates; auth tokens cached in keyring but OAuth roundtrips still occur; higher latency for rapid sequential calls

• Baked safety-profile binaries vs. runtime enforcement

  • Why: Provides strong auditability and cannot be bypassed at runtime; suitable for restricted deployment environments
  • Consequence: Requires pre-build profile definition and separate binary distribution; less flexibility than runtime flags

• Auto-generated command documentation vs. hand-written

  • Why: Ensures docs always match code; reduces maintenance burden and drift
  • Consequence: Build step required to regenerate docs; documentation format is constrained by code annotations

• Multiple OAuth clients + service accounts vs. single identity

  • Why: Supports Workspace admin flows, multi-tenant scenarios, and CI/CD with service accounts without interactive auth
  • Consequence: Increased complexity in credential selection logic and account switching; more state to manage

• Real-time event streaming or webhooks—CLI is request-response only
• Persistent state or caching layer (e.g., database)—stateless invocation model
• GUI or web dashboard—terminal/script-native only
• Offline-first or sync—always requires Google API connectivity
• End-to-end encryption of data at rest—relies on Google Drive and OS keychain security

1. OAuth token refresh expiration: External+Testing Google Cloud projects see tokens expire after 7 days—publish the app to Production for long-lived tokens. 2) API enablement latency: enabling APIs in Google Cloud Console requires propagation time before CLI can use them; will return 'accessNotConfigured' if called too soon. 3) GOG_KEYRING_PASSWORD required: file keyring backend (used in Docker) requires this env var set; omitting it will hang during auth operations. 4) Service account scopes: Workspace domain-wide delegation requires separate setup; consumer gmail.com accounts cannot access Admin Directory or Chat APIs. 5) Go 1.26.2 exact version: older Go versions will fail to build due to undeclared language features (tzdata_test.go suggests timezone handling requirements).

• OAuth 2.0 Refresh Token Rotation & Expiry — gogcli must handle Google's token expiration policies (7-day expiry for External+Testing apps, long-lived for Production) and refresh token rotation; understanding this prevents silent auth failures in long-running scripts.
• Google Workspace Domain-Wide Delegation — Admin commands (admin users, groups) require domain-wide delegation for service accounts; user OAuth cannot access Admin Directory APIs—this architectural split affects command availability per account type.
• CLI Command Allowlist/Denylist & Safety Profiles — bake-safety-profile generates restricted binaries for agent automation; this security pattern prevents accidental destructive operations (delete Drive files, modify user accounts) by pre-computing which commands are available.
• Keyring Backends (OS Keychain, File, Encrypted) — gogcli abstracts credential storage across Windows (wincred), macOS (keychain), Linux (secret-service), and Docker (file+age encryption); understanding which backend is active (GOG_KEYRING_BACKEND env var) is critical for deployment.
• JSON5 Configuration Parsing — gogcli uses yosuke-furukawa/json5 for config files, allowing trailing commas and comments in JSON—this enables more maintainable multi-account configs vs strict JSON.
• gRPC vs REST API Trade-offs — google.golang.org/api primarily wraps REST endpoints, not gRPC; this affects latency, connection pooling, and streaming capabilities for high-volume Gmail/Calendar/Drive operations.
• Kong CLI Struct Tag Routing — gogcli uses alecthomas/kong's struct embedding pattern for hierarchical commands (gog admin users list); modifying command structure requires understanding nested struct tags and validation rules.

• googleapis/google-cloud-go — Official Google Cloud Go SDK; gogcli wraps google.golang.org/api from this repo for Gmail, Calendar, Drive access
• google/google-api-go-client — Google API Go client generator; provides the underlying client libraries (gmail, calendar, drive) that gogcli depends on
• 99designs/keyring — Cross-platform credential storage backend used by gogcli for secure OAuth token and client secret management
• alecthomas/kong — CLI command parser and help generator used for gogcli's command routing and --help documentation
• steipete/gomail — Potential companion repo (if it exists) for Go-based email manipulation beyond gogcli's Gmail API wrapper

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for gog-auth commands with multiple OAuth clients

The repo advertises 'multiple Google accounts and OAuth clients' as a key feature, but cmd/gog/main_test.go appears minimal. The auth subcommands (gog-auth-add, gog-auth-alias-, gog-auth-credentials-) lack documented test coverage for the credential switching workflow. This would validate the core multi-account flow that differentiates gogcli.

• [ ] Review cmd/gog/main_test.go and cmd/gog/tzdata_test.go to understand existing test patterns
• [ ] Create cmd/gog/auth_integration_test.go with tests for: adding multiple accounts, switching between them via aliases, and listing credentials
• [ ] Test credential persistence across the keyring backends (99designs/keyring supports multiple backends)
• [ ] Add test fixtures for OAuth2 tokens and service account JSON in testdata/
• [ ] Ensure tests cover the docs/commands/gog-auth-*.md workflows

Document and test the bake-safety-profile build mode for restricted deployments

The repo mentions 'baked safety-profile binaries' and has cmd/bake-safety-profile/main.go with only main_test.go, but there's no docs/commands/gog-bake-safety-profile.md or docs/SAFETY_PROFILES.md explaining this critical feature. New contributors can't understand how to use this for agent/CI deployments with allowlists/denylists.

• [ ] Review cmd/bake-safety-profile/main.go to understand the safety profile mechanism
• [ ] Create docs/SAFETY_PROFILES.md explaining: what safety profiles are, use cases (agents, CI), how to build them, and example allowlist/denylist configurations
• [ ] Add cmd/bake-safety-profile/main_test.go tests (currently empty) covering: loading config files, validating command allowlists/denylists, and generating restricted binaries
• [ ] Add a workflow example in .github/workflows/ or docs/RELEASING.md showing how to build and distribute safety-profile binaries
• [ ] Add testdata/safety-profile-examples/ with sample configs

Complete test coverage for cmd/gog/main.go command dispatch and error handling

cmd/gog/main.go is the CLI entrypoint using alecthomas/kong for command routing, but cmd/gog/main_test.go is sparse. Missing tests for: invalid commands, help output, version flag, and error propagation from subcommands. This is critical since agents rely on predictable exit codes (see docs/commands/gog-agent-exit-codes.md).

• [ ] Review .github/workflows/ci.yml to see current test coverage gaps
• [ ] Add table-driven tests in cmd/gog/main_test.go for: valid commands with --help, invalid command names, --version flag, --json/--plain output flags on various commands
• [ ] Test that stderr contains human hints while stdout is clean JSON/plain output (as documented in README)
• [ ] Add tests verifying exit codes match docs/commands/gog-agent-exit-codes.md (e.g., exit 1 for auth errors, exit 2 for validation errors)
• [ ] Use testify assertions (already a dependency) and add golden file tests for command output stability

• Add test coverage for cmd/gog/tzdata_test.go timezone handling—calendar events across DST boundaries likely need validation; check if all Google Workspace timezones are tested.
• Generate missing command docs: docs/commands/ is incomplete (only partial file list shown); write auto-generation logic to crawl all Kong subcommands and create .md for untested paths like gog-task-*, gog-appscript-deploy, etc.
• Enhance error messages for common OAuth failures: create a diagnostics module in internal/ that translates Google API errors (401 Unauthorized, 403 Forbidden, accessNotConfigured) into helpful next steps (check GOG_ACCOUNT, run 'gog auth doctor', enable API in Cloud Console).

The gogcli project demonstrates generally solid security practices with encryption support (age library), keyring integration, and OAuth2 support. However, there are minor concerns around version validation (Go 1.26.2 appears incorrect), credential storage in file-based keyrings, and the need for automated dependency vulnerability scanning.

• Medium · Outdated Go Version — go.mod (go 1.26.2). The project targets Go 1.26.2, which appears to be a future/invalid version. The latest stable Go version as of early 2024 is 1.21.x or 1.22.x. This indicates either a typo in the go.mod file or a misconfiguration that could lead to unexpected behavior or missed security updates. Fix: Update to a valid, current Go version (1.22.x or later). Verify the correct version in the go.mod file and update all CI/CD configurations accordingly.
• Medium · Keyring Backend Configuration Exposure — README.md (Docker instructions), Dockerfile. The README documents using GOG_KEYRING_BACKEND=file in environment variables for Docker containers. File-based keyrings store secrets on disk and may be less secure than OS-level keyrings. If the volume is not properly secured or backed up, credentials could be exposed. Fix: Document security best practices for keyring backends. Recommend using OS-native keyrings (macOS keychain, Windows credential manager) for desktop use. For containers, ensure volume encryption and strict access controls. Consider defaulting to more secure backends.
• Low · OAuth Token Handling in CLI — cmd/gog, internal/cmd, auth-related commands. The project handles OAuth2 tokens and credentials via command-line interfaces. While the code structure suggests proper handling (separate credentials management, encryption via age), tokens displayed in logs or history could be exposed. Fix: Ensure tokens are never logged or displayed in plain text. Implement token masking in output. Use --secure or --hide-secrets flags by default. Add warnings in documentation about shell history exposure.
• Low · Service Account Credential Storage — docs/commands/gog-auth-service-account-set.md, internal/auth. The project supports Workspace service accounts (gog-auth-service-account-set). Service account JSON files contain sensitive credentials that must be protected during transit and storage. Fix: Document secure handling of service account JSON files. Implement file permission checks (warn if world-readable). Consider requiring explicit confirmation before importing service accounts. Document encryption at rest recommendations.
• Low · External Dependency on google.golang.org/api — go.mod (google.golang.org/api v0.277.0). The project depends on google.golang.org/api v0.277.0 (a very high version number that seems unusual). Large dependency trees increase attack surface. While Google's official SDK is generally trustworthy, version consistency should be verified. Fix: Verify the google.golang.org/api version is correct and current. Run go mod tidy and go mod verify. Consider using go mod audit (Go 1.22+) to check for known vulnerabilities. Regularly update dependencies.
• Low · JSON5 Parser Usage — go.mod (github.com/yosuke-furukawa/json5 v0.1.1). The project uses yosuke-furukawa/json5 v0.1.1 for JSON5 parsing. JSON5 is a non-standard extension that allows comments and trailing commas. This could introduce parsing inconsistencies or security issues if user-controlled input is parsed. Fix: Review all usages of JSON5 parser to ensure only trusted configuration files are parsed. If parsing user input, validate and sanitize. Consider using standard JSON for security-sensitive operations.
• Low · Missing SBOM and Dependency Audit — .github/workflows/ci.yml. No evidence of Software Bill of Materials (SBOM) generation or automated dependency vulnerability scanning in CI/CD. The GitHub workflows exist but specific security scanning steps are not visible in the provided snippets. Fix: Implement automated dependency scanning using go mod audit, Snyk, or GitHub's dependency scanning. Generate and publish SBOM for releases. Add security checks to CI/CD pipeline to fail builds on known vulnerabilities.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.