gws docs: richformat commands fail or behave unexpectedly in several cases

[omriariav]

Summary

When using gws docs with --content-format richformat to apply formatting to Google Docs, several issues were encountered.

Issues

1. --at flag silently ignored with richformat

When using gws docs insert with --content-format richformat, the --at flag is ignored with only a warning:

warning: --at is ignored when --content-format is richformat

This is confusing because the user might expect positional insertion. Either the flag should be respected (by wrapping the requests with a location), or the CLI should error out instead of silently ignoring it.

2. append with richformat fails on valid API requests

Using gws docs append with richformat containing updateDocumentStyle fails:

gws docs append $DOC_ID --text '[
  {"updateDocumentStyle": {"documentStyle": {"defaultHeaderId": ""}, "fields": "defaultHeaderId"}}
]' --content-format richformat

Error:

failed to append text: googleapi: Error 400: Invalid requests[0].updateDocumentStyle: Unallowed field: defaultHeaderId

While this specific field may be invalid, the error message comes from the Google API but is surfaced as a gws error, making it hard to distinguish between CLI bugs and API validation errors.

3. Position boundary off-by-one confusion

format and set-paragraph-style fail when using the document text length as the end index:

# Python reports text length as 5837
gws docs format $DOC_ID --from 1 --to 5836 --font-size 11

Error:

Index 5836 must be less than the end index of the referenced segment, 5833.

The --include-formatting output doesn't include position indices for each element, so users have to guess the valid range. It would help if:

• read --include-formatting included startIndex/endIndex for each element
• Or there was a way to query the valid end index of the document

4. No way to set paragraph direction via set-paragraph-style

The set-paragraph-style command supports --alignment and --line-spacing but not --direction (RTL/LTR). For Hebrew/Arabic documents this is essential. Users must fall back to richformat to set direction:

gws docs insert $DOC_ID --at 1 --text '[
  {"updateParagraphStyle": {"range": {"startIndex": 1, "endIndex": 5832}, "paragraphStyle": {"direction": "RIGHT_TO_LEFT"}, "fields": "direction"}}
]' --content-format richformat

Feature request: Add --direction RTL|LTR flag to set-paragraph-style.

5. No --font-family flag on format command

The format command supports --bold, --italic, --font-size, and --color, but not --font-family. Users must use richformat to change fonts.

Feature request: Add --font-family "David Libre" flag to format.

Environment

• gws version: latest
• OS: macOS (Darwin 25.3.0)
• Context: Creating RTL Hebrew documents with IDF-style formatting