# 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
```bash
# Clone the repository
git clone https://github.com/maksdizzy/google-forms-cli
cd google-forms-cli
# Install with uv
uv sync
```
### 2. Setup OAuth
```bash
# 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
```bash
# 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
```bash
# 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:
```yaml
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:
```bash
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](https://console.cloud.google.com)
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](https://developers.google.com/oauthplayground/)
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**
```bash
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:
```bash
# Both commands work identically
uv run gforms forms list
uv run gtools forms list
```
## Troubleshooting
**OAuth Errors:**
```bash
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