README
¶
google-readwrite (grw)
A read-write command-line interface for Gmail cleanup and organization. grw is
the read-write companion to gro:
it reads and organizes mail the same way, and adds the operations gro
deliberately cannot perform.
What it adds over gro
| Command | What it does |
|---|---|
grw mail delete |
Move messages to Trash (default). --permanent erases them irreversibly, behind a typed confirmation and the broad mail.google.com scope. |
grw mail restore |
Move messages back out of Trash (undo a plain delete). |
grw mail folder create/rename/rm |
Manage labels as folders. "Receipts/2026" nests a subfolder. |
grw mail filter list/create/rm |
Manage Gmail filters — match on --from/--to/--subject/--query/--has-attachment, act with --add-label/--archive/--mark-read/--star/--trash. |
Everything gro does — search, read, archive, label, move, star,
mark-read, drafts — is available under grw mail too, so a full cleanup
workflow lives in one tool.
Install
brew install open-cli-collective/tap/google-readwrite
grw init
grw init reuses an existing gro OAuth client automatically (no re-paste); you
grant consent once for grw's scopes.
Isolation and safety
grw stores its credentials in a separate keyring namespace
(google-readwrite/*) from gro (google-readonly/*). Because gro is
structurally incapable of deleting, sending, or trashing anything, you can hand
an agent gro alone and keep grw gated to contexts you trust. The two never
collide.
Delete defaults to Trash (recoverable ~30 days). Permanent deletion requires an
explicit --permanent flag and a typed confirmation.
Development
make check # tidy + lint + test (race) + build
make install # build and install grw locally
grw is a thin CLI built on
google-cli-common;
almost all logic (OAuth, the Gmail client, rendering, the shared command
surface) lives there. Family-wide standards are in
cli-common.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
grw
command
Package main is the entry point for the grw (google-readwrite) CLI.
|
Package main is the entry point for the grw (google-readwrite) CLI. |
|
internal
|
|
|
appidentity
Package appidentity declares google-readwrite's CLI identity: the config/ keyring directory name, default credential ref, product name, and the OAuth scope set this CLI requests.
|
Package appidentity declares google-readwrite's CLI identity: the config/ keyring directory name, default credential ref, product name, and the OAuth scope set this CLI requests. |
|
cmd/mail
Package mail is grw's Gmail command surface.
|
Package mail is grw's Gmail command surface. |
|
cmd/root
Package root provides the top-level grw command and global flags.
|
Package root provides the top-level grw command and global flags. |
|
gmailrw
Package gmailrw extends the shared read/organize Gmail client (google-cli-common/gmail) with the read-WRITE operations grw adds: trash and permanent delete, label lifecycle (create/rename/delete — the "folders" and "subfolders" users think in), and filter management.
|
Package gmailrw extends the shared read/organize Gmail client (google-cli-common/gmail) with the read-WRITE operations grw adds: trash and permanent delete, label lifecycle (create/rename/delete — the "folders" and "subfolders" users think in), and filter management. |