README
¶
google-cli-common
Shared Go library for the Open CLI Collective's Google CLIs. It holds everything
that would otherwise be duplicated between them: the Google OAuth flow, the API
service clients (Gmail, Calendar, Contacts, Drive, People), credential/config/
cache state, rendering and bulk-operation helpers, and the cobra command
scaffolding (init, credential management, the mail command surface, root
wiring).
Each CLI is a thin binary that registers a config.Identity at startup and
composes the pieces it needs:
google-readonly(gro) — non-destructive: read plus labeling/archiving/RSVP/etc.google-readwrite(grw) — read-write Gmail cleanup: delete, filters, and label (folder) lifecycle.
The identity seam
One shared library backs multiple CLIs because everything CLI-specific is
funneled through a single config.Identity, registered once from main before
any other call:
config.Register(config.Identity{
DirName: "google-readwrite", // config/cache dir, keyring service, env-var prefix
DefaultRef: "google-readwrite/default", // default <service>/<profile> credential ref
ProductName: "grw", // user-facing name in messages
Scopes: appidentity.Scopes, // OAuth scopes this CLI requests
ScopeDescriptions: appidentity.ScopeDescriptions,
SiblingDirNames: []string{"google-readonly"}, // OAuth clients this CLI may reuse
})
DirName alone drives the config/cache directory, the keyring service segment,
and the derived <SERVICE>_KEYRING_BACKEND / <SERVICE>_KEYRING_PASSPHRASE /
<SERVICE>_CREDENTIAL_REF env vars, so two CLIs never collide.
Layout
| Package | Responsibility |
|---|---|
config, keychain, auth |
Config file, OS-keyring token storage, and the Google OAuth flow |
gmail, calendar, contacts, drive, people |
API clients and data models |
mailcmd, initcmd, configcmd, setcred, refreshcmd, rootutil |
Shared cobra command packages and root scaffolding |
bulk, output, format, view, errors, log, cache, zip, version |
Rendering, bulk-operation, and support utilities |
testutil, credtest |
Test fixtures, assertions, and a hermetic credential environment |
Development
make check # tidy + lint + test (race) + build
Secret/state handling, output conventions, and repository layout follow the
Open CLI Collective standards in
cli-common.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auth provides OAuth2 authentication and credential management for Google APIs.
|
Package auth provides OAuth2 authentication and credential management for Google APIs. |
|
Package bulk provides shared ID resolution and result types for bulk operations.
|
Package bulk provides shared ID resolution and result types for bulk operations. |
|
Package cache wraps cli-common/cache for gro's Drive metadata cache.
|
Package cache wraps cli-common/cache for gro's Drive metadata cache. |
|
Package calendar provides a client for the Google Calendar API.
|
Package calendar provides a client for the Google Calendar API. |
|
Package config provides centralized configuration management for the application.
|
Package config provides centralized configuration management for the application. |
|
Package configcmd implements the config command and subcommands.
|
Package configcmd implements the config command and subcommands. |
|
Package contacts provides a client for the Google People API.
|
Package contacts provides a client for the Google People API. |
|
Package credtest provides a hermetic credential environment for tests (§1.12 test obligation).
|
Package credtest provides a hermetic credential environment for tests (§1.12 test obligation). |
|
Package drive provides a client for the Google Drive API.
|
Package drive provides a client for the Google Drive API. |
|
Package errors provides error types for distinguishing between user errors and system errors, allowing commands to provide appropriate guidance.
|
Package errors provides error types for distinguishing between user errors and system errors, allowing commands to provide appropriate guidance. |
|
Package format provides shared formatting utilities for consistent output.
|
Package format provides shared formatting utilities for consistent output. |
|
Package gmail provides a client for the Gmail API.
|
Package gmail provides a client for the Gmail API. |
|
Package initcmd implements the gro init command — a single-run guided OAuth setup wizard built on charmbracelet/huh.
|
Package initcmd implements the gro init command — a single-run guided OAuth setup wizard built on charmbracelet/huh. |
|
Package keychain is gro's credential adapter.
|
Package keychain is gro's credential adapter. |
|
Package log provides simple structured logging with verbosity levels.
|
Package log provides simple structured logging with verbosity levels. |
|
Package mailcmd implements the mail command and subcommands.
|
Package mailcmd implements the mail command and subcommands. |
|
Package migrationsink is the leaf holding the §1.8 one-time-migration signal.
|
Package migrationsink is the leaf holding the §1.8 one-time-migration signal. |
|
Package output provides shared output utilities for formatting and printing data to various destinations.
|
Package output provides shared output utilities for formatting and printing data to various destinations. |
|
Package people provides a client for the Google People API focused on the authenticated user's own profile (people/me).
|
Package people provides a client for the Google People API focused on the authenticated user's own profile (people/me). |
|
Package refreshcmd implements `refresh` — the top-level cache control surface per cli-common/docs/working-with-state.md §4.6.
|
Package refreshcmd implements `refresh` — the top-level cache control surface per cli-common/docs/working-with-state.md §4.6. |
|
Package rootutil holds the root-command scaffolding shared by every CLI built on this library: the standard global flags (--verbose, --no-color, --backend, --ref), the PersistentPreRunE wiring that records the backend/credential-ref selection for the next keychain.Open call, and the migration-notice flush that must wrap execution.
|
Package rootutil holds the root-command scaffolding shared by every CLI built on this library: the standard global flags (--verbose, --no-color, --backend, --ref), the PersistentPreRunE wiring that records the backend/credential-ref selection for the next keychain.Open call, and the migration-notice flush that must wrap execution. |
|
Package setcred implements `set-credential` — the low-level, scriptable credential ingress (§1.5.2).
|
Package setcred implements `set-credential` — the low-level, scriptable credential ingress (§1.5.2). |
|
Package testutil provides test assertion helpers and sample data fixtures.
|
Package testutil provides test assertion helpers and sample data fixtures. |
|
Package version provides build-time version information.
|
Package version provides build-time version information. |
|
Package view provides a small, consistent output helper for interactive CLI flows (Success / Error / Info / Printf / Println).
|
Package view provides a small, consistent output helper for interactive CLI flows (Success / Error / Info / Printf / Println). |
|
Package zip provides secure zip archive extraction with path traversal protection.
|
Package zip provides secure zip archive extraction with path traversal protection. |
Click to show internal directories.
Click to hide internal directories.