ExtraForm

Pull, edit, and push Google Forms using local files.

ExtraForm transforms Google Forms into a file-based representation optimized for LLM agents. It follows the same pull/diff/push workflow as ExtraSheet.

Installation

pip install extraform

Or with uvx:

uvx extraform pull <form_url>

Quick Start

# 1. Pull a form
extraform pull https://docs.google.com/forms/d/1FAIpQLSd.../edit

# 2. Edit form.json in your editor or with an AI agent

# 3. Preview changes
extraform diff 1FAIpQLSd...

# 4. Apply changes
extraform push 1FAIpQLSd...

Commands

pull

Download a Google Form to a local folder:

extraform pull <form_url_or_id> [output_dir]

Options:

• --responses - Include form responses (read-only)
• --max-responses N - Maximum responses to fetch (default: 100)
• --no-raw - Don't save raw API responses

diff

Preview changes without applying them:

extraform diff <folder>

Outputs the batchUpdate JSON to stdout.

push

Apply changes to the Google Form:

extraform push <folder>

On-Disk Format

After pulling a form, you'll have:

<form_id>/
  form.json                 # Form structure - edit this!
  responses.tsv             # Read-only snapshot of responses
  .raw/
    form.json               # Raw API response
    responses.json          # Raw responses (if fetched)
  .pristine/
    form.zip                # Original state for diff

form.json

The form structure mirrors the Google Forms API but is cleaned up for readability:

{
  "formId": "1FAIpQLSd...",
  "info": {
    "title": "My Survey",
    "description": "Please fill out this survey"
  },
  "items": [
    {
      "itemId": "abc123",
      "title": "What is your name?",
      "questionItem": {
        "question": {
          "required": true,
          "textQuestion": {
            "paragraph": false
          }
        }
      }
    }
  ]
}

Question Types

Non-Question Items

Limitations

• File upload questions: Cannot be created via API (read-only)
• Responses: Read-only, cannot modify submitted responses
• documentTitle: Read-only, update via Google Drive

Development

cd extraform
uv sync
uv run pytest tests/ -v
uv run ruff check . && uv run ruff format .
uv run mypy src/extraform

License

MIT