gw-forms

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

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.

$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

$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:

// 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}