-
Notifications
You must be signed in to change notification settings - Fork 568
Open
Description
Body
## Summary
While using gws via extension skills, two documentation gaps caused repeated trial-and-error:
1. `fields` usage is unclear in many command examples (users may try `--fields` as a standalone flag, which fails in gws for several commands).
2. Gmail draft creation with raw message does not clearly document non-ASCII `Subject` header encoding (RFC 2047), causing garbled Chinese/Japanese/Korean subjects.
## Environment
- gws CLI: `0.7.0`
- Extension: `google-workspace-cli v0.7.0`
- OS: macOS
## Problem details
### A) `fields` placement confusion
Users may try:
```bash
gws drive files list --params '{"q":"..."}' --fields "files(id,name)"This returns validation errors in gws command patterns where --fields is not a top-level flag.
What worked:
gws drive files list --params '{"q":"...", "fields":"files(id,name)"}'B) Raw Gmail draft subject garbling
When building raw RFC 2822 message and using non-ASCII subject directly:
Subject: 三月分享老師邀請
subject may appear garbled.
Using RFC 2047 encoded-word works:
Subject: =?UTF-8?B?...?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Requested docs improvements
- Add explicit examples showing
fieldsinside--paramsJSON for relevant APIs. - Add a "Common pitfalls" section for gws skills:
- unsupported standalone
--fields - quoting/JSON pitfalls for
--params/--json
- unsupported standalone
- Add Gmail raw draft example with RFC 2047 subject encoding.
- In skill docs (especially Gmail/Drive/Sheets), include one end-to-end example with correct param structure and UTF-8-safe headers.
Why this matters
These are high-frequency mistakes for agent-driven workflows and CLI newcomers; clarifying docs would reduce retries, token usage, and user confusion.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels