GL Form Filler CLI (gl-form-filler)

A production-quality, cross-platform CLI application designed to automate filling Google Forms that you fill repeatedly.

Enter your personal information only once in a shared Global Profile. Afterwards, easily configure multiple forms and run:

gl-form-filler

to open the modern interactive menu and automate your form filling every day.

Key Features

• Multi-Form Support: Configure multiple Google Forms (daily-survey, university-form, etc.), each with its own URL, description, and saved field choices.
• Dynamic Google Form Discovery: Extracts form fields, types, and radio/select choices live directly from Google Forms using Playwright and Google Forms structural data (FB_PUBLIC_LOAD_DATA_). Zero hardcoded option choices.
• Zero Emojis & Developer UX: Clean, cross-platform terminal badges ([OK], [FAIL], [WARN], [INFO], [STEP]) and dynamic operation spinners.
• System Diagnostics (doctor): Diagnose Node.js version, platform, browser executable paths, AppData directory, and encryption health.
• Encrypted Global Personal Profile (profile): Encrypts and stores shared personal data (Name In Arabic, Name In English, WhatsApp, Mobile, ID Number, Email) once in profile.enc. Includes masked viewing (Mohamed Bakr, b***@gmail.com).
• Machine-Readable JSON Output (--json): Output structured JSON for automation scripts (gl-form-filler list --json).
• Zero Auto-Submit Guarantee: The application NEVER automatically submits the form. The browser remains open until you review fields and manually click Submit when ready.
• AES-256-GCM Encryption & OS Keychain Integration: Authenticated encryption for personal data and form configurations using crypto.scrypt() and OS credential stores (Windows Credential Manager / DPAPI, macOS Keychain, Linux Secret Service).
• Isolated Browser Profile: Uses Playwright with a dedicated browser profile located in your OS application data directory (<appDataDir>/browser/profile/), avoiding conflicts with your default browser.
• Dry-Run Mode: Test profile decryption, live form discovery, answer validation, and date calculations without filling fields using --dry-run.

Installation & Setup

Requirements

• Node.js: >= 18.0.0
• Browsers: Google Chrome, Brave Browser, Microsoft Edge, or Chromium

Build & Global Link

# Clone repository
git clone <repository-url>
cd autoFillGlForm

# Install dependencies
npm install

# Build TypeScript
npm run build

# Link binary globally
npm link

Usage Guide

1. Interactive Main Menu (Default Command)

Running gl-form-filler with no arguments opens a modern interactive terminal menu:

gl-form-filler

Output:

  ____ _     _____                     _____ _ _ _                      
 / ___| |   |  ___|__  _ __ _ __ ___  |  ___(_) | | ___ _ __            
| |  _| |   | |_ / _ \| '__| '_ ` _ \ | |_  | | | |/ _ \ '__|           
| |_| | |___|  _| (_) | |  | | | | | ||  _| | | | |  __/ |              
 \____|_____|_|  \___/|_|  |_| |_| |_||_|   |_|_|_|\___|_|              

  GL Form Filler CLI v1.0.0
  Secure, Cross-Platform Browser Automation CLI for Google Forms
  Zero Auto-Submit Guarantee • AES-256-GCM Encryption • Dynamic Discovery

? What would you like to do?
❯ Run a form
  Configure a new form (setup)
  List configured forms
  Manage global profile
  View application configuration
  Run system diagnostics (doctor)
  Exit

2. Setup a New Form (setup) (Alias: init)

Configure a new Google Form profile:

gl-form-filler setup

or specify a form name directly:

gl-form-filler setup daily-survey

Workflow executed:

1. Prompts for Form Name (slugified e.g. daily-survey), Description, and Form URL.
2. Opens form URL and discovers fields and live choices with an active spinner.
3. Prompts for Global Profile (profile.enc) if not created yet.
4. Interactively prompts for form-specific choices using the live options extracted directly from Google Forms.
5. Displays a concise summary box and asks for confirmation.
6. Saves encrypted configuration to forms/<name>.enc and metadata to registry.json.

3. Run a Specific Form (run) (Alias: r)

Execute automated filling for a specific form:

gl-form-filler run daily-survey

or direct form alias:

gl-form-filler daily-survey

Workflow executed:

1. Loads profile.enc and forms/daily-survey.enc.
2. Calculates tomorrow's date (YYYY-MM-DD).
3. Launches browser and opens Google Form URL with active progress spinners.
4. Discovers live form options and validates saved choices.
5. Fills date, personal text fields, and radio choices.
6. Validates populated fields.
7. Displays completion summary and waits for Enter to close browser session.

4. System Diagnostics (doctor)

Diagnose Node.js, browser executables, and storage health:

gl-form-filler doctor

Output:

GL FORM FILLER DOCTOR

[OK] Node.js v24.19.0 (>= v18.0.0)
[OK] OS Platform: win32 (x64)
[OK] AppData Directory: C:\Users\Mmoha\AppData\Roaming\gl-form-filler
[OK] Browser Executable: Brave Browser (C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe)
[WARN] Encryption: AES-256-GCM (Master password manual prompt mode)
[OK] Global Personal Profile: Present and encrypted
[OK] Configured Google Forms: 1 form(s) configured

[OK] Result: All environment and storage checks passed successfully.

5. Encrypted Global Profile Management (profile)

View (masked), edit, or clear your global personal profile:

gl-form-filler profile

6. List Configured Forms (list) (Alias: ls)

List all configured forms with their names and descriptions:

gl-form-filler list

Machine-readable JSON output:

gl-form-filler list --json

7. Dry Run Mode (--dry-run)

Validate form accessibility, live options discovery, and saved answers without filling fields or modifying the form:

gl-form-filler run daily-survey --dry-run

Global Options & Exit Codes

Global Options

• -v, --version: Output application version
• -h, --help: Display help screen
• --verbose: Enable detailed operational log output
• --debug: Enable technical debugging diagnostic output
• -q, --quiet: Suppress non-essential log output
• --no-color: Disable ANSI colors and styling
• --dry-run: Validate structure and options without modifying form

Exit Codes

• 0: Success
• 1: General Failure
• 2: Invalid CLI Usage (CliUsageError)
• 3: Configuration / Storage Failure (ConfigError, AuthError, StorageError)
• 4: Browser / Form Automation Failure (BrowserError, FormAutomationError, FormDiscoveryError)
• 5: User Cancellation (UserCancelledError)

Storage Architecture

appData/
└── gl-form-filler/
    ├── config.json               # Non-sensitive app settings (browser, typingDelay, timeout)
    ├── registry.json             # Non-sensitive form metadata registry ([{ name, description }])
    ├── profile.enc               # Encrypted Global Profile (nameArabic, nameEnglish, whatsapp, mobile, idNumber, email)
    └── forms/                    # Encrypted Form-specific Configurations directory
        ├── daily-survey.enc
        ├── university-form.enc
        └── registration-form.enc

Automated Tests

Run the unit test suite:

npm test

Includes 24 unit tests covering:

• Encryption & decryption roundtrips with tampered ciphertext/authTag rejection.
• Form Registry CRUD operations & form resolver logic.
• Date boundary calculations (month-end, year-end, leap years).
• 14-digit Egyptian National ID & phone number validation.
• Concurrency lock management (AppLock).
• Zero Auto-Submit code verification.

License

MIT License. See LICENSE for details.