Skip to content

docs: clarify --params/fields usage and RFC 2047 subject encoding for gmail drafts raw #266

@shuotao

Description

@shuotao

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

  1. Add explicit examples showing fields inside --params JSON for relevant APIs.
  2. Add a "Common pitfalls" section for gws skills:
    • unsupported standalone --fields
    • quoting/JSON pitfalls for --params/--json
  3. Add Gmail raw draft example with RFC 2047 subject encoding.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions