Google Tools CLI

Command-line tool for managing Google Workspace - create forms, add questions, export responses, read spreadsheets.

Features

• Full form management - Create, update, delete, duplicate forms
• All question types - 12 Google Forms question types supported
• Response export - Export responses to CSV
• Google Sheets - Read and export spreadsheet data
• YAML templates - Create complex forms from simple YAML files
• Interactive OAuth wizard - Easy setup for non-technical users
• Cursor Skill - Works as an AI agent skill in Cursor IDE

Quick Start

1. Install

# Clone the repository
git clone https://github.com/maksdizzy/google-forms-cli
cd google-forms-cli

# Install with uv
uv sync

2. Setup OAuth

# Run interactive setup wizard
uv run gtools auth setup

The wizard guides you through:

1. Creating OAuth credentials in Google Cloud Console
2. Getting a refresh token
3. Saving credentials to .env

3. Use

# List your forms
uv run gtools forms list

# Create a new form
uv run gtools forms create "My Survey"

# Add a question
uv run gtools forms add-question FORM_ID --type MULTIPLE_CHOICE --title "Rate us" --options "1,2,3,4,5"

# Export responses
uv run gtools forms export FORM_ID --output responses.csv

# Read a spreadsheet
uv run gtools sheets read SPREADSHEET_ID

CLI Structure

gtools
├── auth          # Authentication management
│   ├── setup     # Interactive OAuth wizard
│   └── check     # Verify credentials
├── forms         # Google Forms operations
│   ├── list      # List all forms
│   ├── create    # Create new form
│   ├── get       # Get form details
│   ├── update    # Update form
│   ├── delete    # Delete form
│   ├── duplicate # Copy form with personalization
│   ├── link      # Get share links
│   ├── add-question    # Add question
│   ├── delete-question # Remove question
│   ├── move-question   # Reorder question
│   ├── add-section     # Add section break
│   ├── responses       # List responses
│   ├── export          # Export to CSV
│   ├── apply           # Create from YAML
│   └── export-template # Export to YAML
└── sheets        # Google Sheets operations
    ├── info      # Get spreadsheet metadata
    ├── list      # List sheets
    └── read      # Read data (table/CSV/JSON)

Commands

Authentication

Command	Description
gtools auth setup	Interactive OAuth setup
gtools auth check	Verify credentials

Form Management

Command	Description
gtools forms list	List all forms
gtools forms create "Title"	Create new form
gtools forms get FORM_ID	Get form details
gtools forms update FORM_ID	Update form
gtools forms delete FORM_ID	Delete form
gtools forms duplicate FORM_ID	Copy form
gtools forms link FORM_ID	Get share links

Questions

Command	Description
gtools forms add-question	Add question
gtools forms delete-question	Remove question
gtools forms move-question	Reorder question
gtools forms add-section	Add section break

Responses

Command	Description
gtools forms responses FORM_ID	List responses
gtools forms export FORM_ID	Export to CSV

Templates

Command	Description
gtools forms apply template.yaml	Create from template
gtools forms export-template FORM_ID	Export to YAML

Google Sheets

Command	Description
gtools sheets info SPREADSHEET_ID	Get spreadsheet metadata
gtools sheets list SPREADSHEET_ID	List sheets
gtools sheets read SPREADSHEET_ID	Read data

Question Types

# Text questions
--type SHORT_ANSWER
--type PARAGRAPH

# Choice questions (use --options)
--type MULTIPLE_CHOICE --options "A,B,C"
--type CHECKBOXES --options "X,Y,Z"
--type DROPDOWN --options "1,2,3"

# Scale questions
--type LINEAR_SCALE --low 1 --high 5
--type RATING --high 5

# Other
--type DATE
--type TIME

YAML Templates

Create forms from YAML files:

form:
  title: "Customer Feedback"
  description: "Share your experience"

questions:
  - type: SHORT_ANSWER
    title: "Your name"
    required: true

  - type: MULTIPLE_CHOICE
    title: "Satisfaction"
    options: [Excellent, Good, Fair, Poor]
    required: true

  - type: PARAGRAPH
    title: "Comments"

Apply with:

uv run gtools forms apply feedback.yaml

See templates/examples/ for more examples:

• feedback_form.yaml - Employee feedback survey
• event_registration.yaml - Event registration form
• customer_satisfaction.yaml - Customer satisfaction survey

OAuth Setup Details

Prerequisites

1. Go to Google Cloud Console
2. Create a new project
3. Enable Google Forms API, Google Drive API, and Google Sheets API
4. Create OAuth 2.0 credentials (Desktop application)

Get Refresh Token

Option 1: OAuth Playground (recommended)

1. Go to OAuth Playground
2. Click Settings → Check "Use your own OAuth credentials"
3. Enter your Client ID and Client Secret
4. Add scopes:
   • https://www.googleapis.com/auth/forms.body
   • https://www.googleapis.com/auth/forms.responses.readonly
   • https://www.googleapis.com/auth/drive.file
   • https://www.googleapis.com/auth/spreadsheets.readonly
5. Authorize and exchange for tokens
6. Copy the refresh token

Option 2: Interactive wizard

uv run gtools auth setup

For Cursor/AI Agents

This tool is designed to work as a skill for AI agents in Cursor IDE.

See skill.md for complete agent instructions including:

• Quick reference for all commands
• Common workflows
• Error handling

Project Structure

google-forms-cli/
├── src/gtools/
│   ├── __init__.py       # Package init
│   ├── cli.py            # Main CLI entry point
│   ├── templates.py      # YAML template engine
│   ├── core/
│   │   ├── auth.py       # OAuth + interactive wizard
│   │   ├── base.py       # BaseAPI class
│   │   └── scopes.py     # OAuth scopes
│   ├── forms/
│   │   ├── api.py        # Google Forms API wrapper
│   │   ├── models.py     # Pydantic models
│   │   └── commands.py   # Forms CLI commands
│   └── sheets/
│       ├── api.py        # Google Sheets API wrapper
│       ├── models.py     # Pydantic models
│       └── commands.py   # Sheets CLI commands
├── templates/
│   └── examples/         # Example YAML templates
├── skill.md              # Cursor agent instructions
├── pyproject.toml        # Project configuration
└── README.md             # This file

Backwards Compatibility

The legacy gforms command still works as an alias:

# Both commands work identically
uv run gforms forms list
uv run gtools forms list

Troubleshooting

OAuth Errors:

uv run gtools auth check  # Verify credentials
uv run gtools auth setup  # Reconfigure if needed

API Errors:

• Verify Form ID with uv run gtools forms list
• Check API quotas in Google Cloud Console

Security

• .env file is gitignored (never committed)
• Refresh token provides account access - keep secure
• Revoke access: https://myaccount.google.com/permissions

License

MIT