From 189a48060f09bc56b2de914404cb8207b5fcd4ea Mon Sep 17 00:00:00 2001 From: abhiram304 Date: Thu, 12 Mar 2026 00:23:07 -0700 Subject: [PATCH 1/4] docs: document helper commands and the + prefix convention Add a "Helper Commands" section to the Advanced Usage chapter of the README explaining: - What the `+` prefix means and why it exists (visually distinct from Discovery-generated method names, no collision risk) - How to discover helpers via `gws --help` - A full reference table of all 23 helper commands across 11 services - Usage examples for the most common helpers (gmail, sheets, calendar, drive, workflow) Fixes discoverability gap: users had no way to learn about helper commands without reading the source code. --- .changeset/document-helper-commands.md | 9 ++++ README.md | 63 ++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 .changeset/document-helper-commands.md diff --git a/.changeset/document-helper-commands.md b/.changeset/document-helper-commands.md new file mode 100644 index 00000000..e9eb6d20 --- /dev/null +++ b/.changeset/document-helper-commands.md @@ -0,0 +1,9 @@ +--- +"@googleworkspace/cli": patch +--- + +Document helper commands (`+` prefix) in README + +Adds a "Helper Commands" section to the Advanced Usage chapter explaining +the `+` prefix convention, listing all 23 helper commands across 11 services +with descriptions and usage examples. diff --git a/README.md b/README.md index 9130ecbd..6a4528c1 100644 --- a/README.md +++ b/README.md @@ -285,6 +285,69 @@ gws sheets spreadsheets values append \ --json '{"values": [["Name", "Score"], ["Alice", 95]]}' ``` +### Helper Commands + +Some services ship hand-crafted helper commands alongside the auto-generated Discovery surface. Helper commands are prefixed with `+` so they are visually distinct and never collide with Discovery-generated method names. + +Run `gws --help` to see both Discovery methods and helper commands together. + +```bash +gws gmail --help # shows +send, +reply, +reply-all, +forward, +triage, +watch … +gws calendar --help # shows +insert, +agenda … +gws drive --help # shows +upload … +``` + +**Full helper reference:** + +| Service | Command | Description | +|---------|---------|-------------| +| `gmail` | `+send` | Send an email | +| `gmail` | `+reply` | Reply to a message (handles threading automatically) | +| `gmail` | `+reply-all` | Reply-all to a message | +| `gmail` | `+forward` | Forward a message to new recipients | +| `gmail` | `+triage` | Show unread inbox summary (sender, subject, date) | +| `gmail` | `+watch` | Watch for new emails and stream them as NDJSON | +| `sheets` | `+append` | Append a row to a spreadsheet | +| `sheets` | `+read` | Read values from a spreadsheet | +| `docs` | `+write` | Append text to a document | +| `chat` | `+send` | Send a message to a space | +| `drive` | `+upload` | Upload a file with automatic metadata | +| `calendar` | `+insert` | Create a new event | +| `calendar` | `+agenda` | Show upcoming events across all calendars | +| `script` | `+push` | Upload local files to an Apps Script project | +| `workflow` | `+standup-report` | Today's meetings + open tasks as a standup summary | +| `workflow` | `+meeting-prep` | Prepare for your next meeting: agenda, attendees, and linked docs | +| `workflow` | `+email-to-task` | Convert a Gmail message into a Google Tasks entry | +| `workflow` | `+weekly-digest` | Weekly summary: this week's meetings + unread email count | +| `workflow` | `+file-announce` | Announce a Drive file in a Chat space | +| `events` | `+subscribe` | Subscribe to Workspace events and stream them as NDJSON | +| `events` | `+renew` | Renew/reactivate Workspace Events subscriptions | +| `modelarmor` | `+sanitize-prompt` | Sanitize a user prompt through a Model Armor template | +| `modelarmor` | `+sanitize-response` | Sanitize a model response through a Model Armor template | +| `modelarmor` | `+create-template` | Create a new Model Armor template | + +**Examples:** + +```bash +# Send an email +gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there" + +# Reply to a message +gws gmail +reply --message-id MESSAGE_ID --body "Thanks!" + +# Append a row to a spreadsheet +gws sheets +append --spreadsheet-id SPREADSHEET_ID --range "Sheet1" --values "Alice,95" + +# Show today's calendar agenda +gws calendar +agenda + +# Upload a file to Drive +gws drive +upload --file ./report.pdf --name "Q1 Report" + +# Morning standup summary +gws workflow +standup-report +``` + ### Model Armor (Response Sanitization) Integrate [Google Cloud Model Armor](https://cloud.google.com/security/products/model-armor) to scan API responses for prompt injection before they reach your agent. From 012161fabc2ddae1ed678a14ef47f615453e4732 Mon Sep 17 00:00:00 2001 From: abhiram304 Date: Thu, 12 Mar 2026 00:31:28 -0700 Subject: [PATCH 2/4] fix(docs): correct +append and +upload examples per Gemini review - gws sheets +append: flag is --spreadsheet (not --spreadsheet-id) and +append has no --range argument - gws drive +upload: file path is a positional argument, not --file flag --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6a4528c1..2a63b834 100644 --- a/README.md +++ b/README.md @@ -336,13 +336,13 @@ gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there" gws gmail +reply --message-id MESSAGE_ID --body "Thanks!" # Append a row to a spreadsheet -gws sheets +append --spreadsheet-id SPREADSHEET_ID --range "Sheet1" --values "Alice,95" +gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95" # Show today's calendar agenda gws calendar +agenda # Upload a file to Drive -gws drive +upload --file ./report.pdf --name "Q1 Report" +gws drive +upload ./report.pdf --name "Q1 Report" # Morning standup summary gws workflow +standup-report From 86a5311ffdd873182321743f250b76f5816903da Mon Sep 17 00:00:00 2001 From: abhiram304 Date: Thu, 12 Mar 2026 00:39:31 -0700 Subject: [PATCH 3/4] docs: clarify script +push is destructive (replaces, not adds) The +push helper replaces all files in an Apps Script project. Update description to reflect this so users understand the action is destructive before running it. Addresses code-review feedback. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2a63b834..9378417c 100644 --- a/README.md +++ b/README.md @@ -314,7 +314,7 @@ gws drive --help # shows +upload … | `drive` | `+upload` | Upload a file with automatic metadata | | `calendar` | `+insert` | Create a new event | | `calendar` | `+agenda` | Show upcoming events across all calendars | -| `script` | `+push` | Upload local files to an Apps Script project | +| `script` | `+push` | Replace all files in an Apps Script project with local files | | `workflow` | `+standup-report` | Today's meetings + open tasks as a standup summary | | `workflow` | `+meeting-prep` | Prepare for your next meeting: agenda, attendees, and linked docs | | `workflow` | `+email-to-task` | Convert a Gmail message into a Google Tasks entry | From 2305514210099da16a94bf310b4ee8466827cd52 Mon Sep 17 00:00:00 2001 From: abhiram304 Date: Thu, 12 Mar 2026 08:39:59 -0700 Subject: [PATCH 4/4] chore(changeset): correct helper command count to 24 across 10 services Addresses code-review feedback noting the count was off. --- .changeset/document-helper-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/document-helper-commands.md b/.changeset/document-helper-commands.md index e9eb6d20..8c308649 100644 --- a/.changeset/document-helper-commands.md +++ b/.changeset/document-helper-commands.md @@ -5,5 +5,5 @@ Document helper commands (`+` prefix) in README Adds a "Helper Commands" section to the Advanced Usage chapter explaining -the `+` prefix convention, listing all 23 helper commands across 11 services +the `+` prefix convention, listing all 24 helper commands across 10 services with descriptions and usage examples.