gw-forms

Files (1)

• SKILL.md

SKILL.md (first lines)

# Forms

Read and write access to Google Forms via the Forms API v1. Reads are flag-driven (form ID,
page size, etc.); writes use a JSON spec file because Forms questions are too schema-heavy
for per-question CLI flags.

## Invocation

```bash
CLI="python3 ${CLAUDE_PLUGIN_ROOT}/cli/gw.py"
```

## Read commands

All read commands accept a form ID or editor URL (`https://docs.google.com/forms/d/<FORM_ID>/edit`).
Responder URLs (`.../forms/d/e/<E_ID>/viewform`) are rejected with a clear error — the segment
after `/d/e/` is a publication ID, not a form ID, and the API will not accept it.

```bash
$CLI forms get FORM_ID --compact
$CLI forms responses FORM_ID [--no-answers] [--page-size N] --compact
$CLI forms response FORM_ID RESPONSE_ID --compact
```

## Write commands

```bash
$CLI forms create --title "..." [--description "..."] [--from-json spec.json]
$CLI forms add-items FORM_ID --from-json items.json [--at INDEX]
$CLI forms update-info FORM_ID [--title "..."] [--description "..."]
$CLI forms delete-item FORM_ID INDEX
```

## JSON spec format

`--from-json` accepts either an array of item specs, or an object `{title, description, items}`.

Supported item types — every type accepts an optional `description` and (for questions) `required`:

```jsonc
// Section divider (forces a new page in the responder UI)
{"type": "section", "title": "About you", "description": "Optional intro text"}

// Short text answer
{"type": "text", "title": "Your name", "required": true}

// Long text answer
{"type": "paragraph", "title": "Tell us more"}
// Equivalent: {"type": "text", "title": "...", "paragraph": true}

// 1–10 (or any range) linear scale
{"type": "linear_scale", "title": "Rate it",
 "low": 1, "high": 10, "low_label": "Bad", "high_label": "Great", "required": true}

// Single-choice radio
{"type": "radio", "title": "Your role?",
 "options": ["Engineer", "Scientist", "Founder", "Other"], "required": true}

// Multi-select
{"type": "checkbox", "title": "Which apply?", "options": ["A", "B", "C"]}

// Dropdown
{"type": "dropdown", "title": "Pick one", "options": ["A", "B", "C"]}

// Date
{"type": "date", "title": "Event date", "include_time": false, "include_year": true}
```

Example full spec for a feedback form:

```json
{
  "title": "Workshop Feedback",
  "description": "Two minutes — your answers shape the next workshop.",
  "items": [
    {"type": "linear_scale", "title": "Overall rating",
     "low": 1, "high": 10, "low_label": "Bad", "high_label": "Great", "required": true},
    {"type": "radio", "title": "Your role?",
     "options": ["Scientist", "Engineer", "Founder", "Other"], "required": true},
    {"type": "paragraph", "title": "What did you like most?", "required": true},
    {"type": "paragraph", "title": "What could be improved?"}
  ]
}
```

## Response Shapes

`get`: form metadata with item summaries.
```json
{
  "formId": "FORM_ID",
  "title": "Anonymous Reporting Form",
  "documentTitle": "Anonymous Reporting Form",
  "description": "...",
  "responderUri": "https://docs.google.com/forms/d/e/.../viewform",
  "revisionId": "00000004",
  "itemCount": 6,
  "settings": {"emailCollectionType": "DO_NOT_COLLECT"},
  "publishSettings": {"publishState": {"isPublished": true, "isAcceptingResponses": true}},
  "items": [
    {"itemId": "0de6f9e9", "title": "Details of Suspected Violation", "type": "section", "required": false},
    {"itemId": "214f88dd", "title": "Date of Report", "type": "dateQuestion", "required": true}
  ]
}
```

`responses`: list of responses with question titles mapped onto each answer.
```json
{
  "formId": "FORM_ID",
  "count": 1,
  "responses": [
    {
      "responseId": "ACYDBN...",
      "createTime": "2026-05-01T04:44:39.545Z",
      "lastSubmittedTime": "2026-05-01T04:44:39.545092Z",
      "respondentEmail": null,
      "answers": [
        {"questionId": "542c6873", "question": "Date of Report", "values": ["2026-04-04"]},

From Elnora-AI/elnora-google-workspace, Apache-2.0.

More from Elnora-AI/elnora-google-workspace