docs: document helper commands and the + prefix convention#427
Conversation
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 <service> --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 detectedLatest commit: 2305514 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the project's documentation by introducing a new section dedicated to helper commands. The primary goal is to improve the discoverability and understanding of these specialized commands, which were previously undocumented and difficult for new users to find. By explaining the Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds valuable documentation for the helper commands, which was previously missing. The new section in the README clearly explains the + prefix convention, provides a comprehensive reference table of all helper commands, and includes usage examples. I've found a couple of small errors in the examples that would cause them to fail for users. My review includes suggestions to correct them. Overall, this is a great improvement to the project's documentation.
README.md
Outdated
| gws calendar +agenda | ||
|
|
||
| # Upload a file to Drive | ||
| gws drive +upload --file ./report.pdf --name "Q1 Report" |
There was a problem hiding this comment.
The example for gws drive +upload is incorrect. The file argument is a positional argument, not an option, so it should not be prefixed with --file.
| gws drive +upload --file ./report.pdf --name "Q1 Report" | |
| gws drive +upload ./report.pdf --name "Q1 Report" |
- 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
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request adds comprehensive documentation for the CLI's helper commands to the README.md. The changes are well-structured and significantly improve discoverability. I've found one high-severity issue in the documentation for the script +push command, where the description omits the destructive nature of the command, which could lead to data loss. I've suggested a more explicit description to prevent this.
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.
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request adds excellent documentation for the CLI's helper commands to the main README.md, significantly improving their discoverability. The new section explains the + prefix convention, provides a complete reference table for all helper commands, and includes helpful usage examples. My review identified a minor inaccuracy in the command and service count within the changeset file, and I've left a comment with a suggestion to correct it. Overall, this is a valuable documentation enhancement.
Addresses code-review feedback noting the count was off.
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request introduces documentation for the helper commands available in the CLI. It adds a new 'Helper Commands' section to the README.md file, which explains the + prefix convention, provides a comprehensive reference table of all 24 helper commands across 10 services, and includes usage examples for common helpers. A corresponding changeset file is also included. The documentation added is accurate and aligns with the helper command implementations in the source code. The changes look good and I have no comments.
3 participants
Summary
+prefix convention — what it means, why it exists, and how it relates to Discovery-generated commandsMotivation
The
+prefix convention was entirely undiscoverable without reading source code. New users runninggws gmail --helpwould see+send,+reply, etc. but have no documentation explaining what the+prefix means or that a richer set of helpers exists across other services.Test plan
src/helpers/*/)🤖 Generated with Claude Code